cnb 0.1.2

# cnb

[![Crates.io](https://img.shields.io/crates/v/cnb.svg)](https://crates.io/crates/cnb)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

[CNB (Cloud Native Build)](https://cnb.cool) 平台的非官方 Rust SDK，基于 CNB OpenAPI 规范自动生成。

## 特性

- 🚀 完整的 CNB API 支持
- 🔒 类型安全的 API 调用
- ⚡ 异步支持 (基于 tokio)
- 📦 模块化设计，按需使用

## 安装

将以下内容添加到你的 `Cargo.toml` 文件中：

```toml
[dependencies]
cnb = "0.1.1"
```

或者使用 cargo 命令：

```bash
cargo add cnb
```

## 快速开始

```rust
use cnb::ApiClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 创建 API 客户端
    let client = ApiClient::new("https://api.cnb.cool".to_string());
    
    // 获取用户信息
    let user = client.users().get_users_username("username".to_string()).await?;
    println!("{:?}", user);
    
    // 获取仓库信息
    let repo = client.repositories().get_repo("owner/repo".to_string()).await?;
    println!("{:?}", repo);
    
    Ok(())
}
```

## API 模块

此 SDK 提供以下 API 模块：

| 模块 | 描述 |
|------|------|
| `activities` | 活动相关 API |
| `ai` | AI 功能相关 API |
| `artifactory` | 制品库相关 API |
| `assets` | 资源文件相关 API |
| `badge` | 徽章相关 API |
| `build` | 构建相关 API |
| `event` | 事件相关 API |
| `followers` | 关注者相关 API |
| `git` | Git 操作相关 API (分支、标签、提交等) |
| `git_settings` | Git 设置相关 API |
| `issues` | Issue 相关 API |
| `knowledge_base` | 知识库相关 API |
| `missions` | 任务相关 API |
| `organizations` | 组织相关 API |
| `pulls` | Pull Request 相关 API |
| `releases` | 发布版本相关 API |
| `repo_labels` | 仓库标签相关 API |
| `repositories` | 仓库相关 API |
| `security` | 安全相关 API |
| `starring` | 收藏/Star 相关 API |
| `users` | 用户相关 API |
| `wiki` | Wiki 相关 API |
| `workspace` | 工作空间相关 API |

## 使用示例

### 仓库操作

```rust
use cnb::ApiClient;

#[tokio::main]
async fn main() -> Result<(), cnb::ApiError> {
    let client = ApiClient::new("https://api.cnb.cool".to_string());
    
    // 获取仓库信息
    let repo = client.repositories().get_repo("aodoo/rust-cnb".to_string()).await?;
    
    // 获取用户的仓库列表
    let repos = client.repositories().get_users_username_repos(
        "username".to_string(),
        None, // search
        None, // filter_type
        None, // flags
        None, // status
        None, // role
        Some(1), // page
        Some(10), // page_size
        None, // desc
        None, // order_by
    ).await?;
    
    Ok(())
}
```

### Issue 操作

```rust
use cnb::ApiClient;
use serde_json::json;

#[tokio::main]
async fn main() -> Result<(), cnb::ApiError> {
    let client = ApiClient::new("https://api.cnb.cool".to_string());
    
    // 获取 Issue 列表
    let issues = client.issues().get_repo_issues(
        "aodoo/rust-cnb".to_string(),
        Some(1), // page
        Some(20), // page_size
        Some("open".to_string()), // state
        None, None, None, None, None, None, None, None, None, None,
    ).await?;
    
    // 创建 Issue
    let new_issue = client.issues().post_repo_issues(
        "aodoo/rust-cnb".to_string(),
        json!({
            "title": "Bug report",
            "body": "Description of the bug"
        }),
    ).await?;
    
    Ok(())
}
```

### Git 操作

```rust
use cnb::ApiClient;

#[tokio::main]
async fn main() -> Result<(), cnb::ApiError> {
    let client = ApiClient::new("https://api.cnb.cool".to_string());
    
    // 获取分支列表
    let branches = client.git().get_repo_git_branches(
        "aodoo/rust-cnb".to_string(),
        Some(1),
        Some(10),
    ).await?;
    
    // 获取标签列表
    let tags = client.git().get_repo_git_tags(
        "aodoo/rust-cnb".to_string(),
        Some(1),
        Some(10),
    ).await?;
    
    // 获取提交信息
    let commit = client.git().get_repo_git_commits_ref(
        "aodoo/rust-cnb".to_string(),
        "main".to_string(),
    ).await?;
    
    Ok(())
}
```

### Pull Request 操作

```rust
use cnb::ApiClient;

#[tokio::main]
async fn main() -> Result<(), cnb::ApiError> {
    let client = ApiClient::new("https://api.cnb.cool".to_string());
    
    // 获取 PR 的评论
    let comments = client.pulls().get_repo_pulls_number_comments(
        "aodoo/rust-cnb".to_string(),
        1, // PR number
        Some(1),
        Some(10),
    ).await?;
    
    // 获取 PR 的文件变更
    let files = client.pulls().get_repo_pulls_number_files(
        "aodoo/rust-cnb".to_string(),
        1,
    ).await?;
    
    Ok(())
}
```

### Release 操作

```rust
use cnb::ApiClient;

#[tokio::main]
async fn main() -> Result<(), cnb::ApiError> {
    let client = ApiClient::new("https://api.cnb.cool".to_string());
    
    // 获取 Release 列表
    let releases = client.releases().get_repo_releases(
        "aodoo/rust-cnb".to_string(),
        Some(1),
        Some(10),
    ).await?;
    
    // 获取最新 Release
    let latest = client.releases().get_repo_releases_latest(
        "aodoo/rust-cnb".to_string(),
    ).await?;
    
    // 通过 Tag 获取 Release
    let release = client.releases().get_repo_releases_tags_tag(
        "aodoo/rust-cnb".to_string(),
        "v1.0.0".to_string(),
    ).await?;
    
    Ok(())
}
```

### 组织操作

```rust
use cnb::ApiClient;

#[tokio::main]
async fn main() -> Result<(), cnb::ApiError> {
    let client = ApiClient::new("https://api.cnb.cool".to_string());
    
    // 获取用户的组织列表
    let groups = client.organizations().get_user_groups(
        Some(1),
        Some(10),
        None,
        None,
    ).await?;
    
    // 获取组织信息
    let org = client.organizations().get_group("org-name".to_string()).await?;
    
    Ok(())
}
```

## 错误处理

所有 API 调用都返回 `Result<T, ApiError>`，其中 `ApiError` 包含以下类型：

```rust
pub enum ApiError {
    /// HTTP 请求错误
    RequestError(reqwest::Error),
    /// HTTP 状态码错误 (包含状态码)
    HttpError(u16),
    /// URL 解析错误
    UrlError(url::ParseError),
    /// JSON 序列化/反序列化错误
    JsonError(serde_json::Error),
}
```

### 错误处理示例

```rust
use cnb::{ApiClient, ApiError};

#[tokio::main]
async fn main() {
    let client = ApiClient::new("https://api.cnb.cool".to_string());
    
    match client.repositories().get_repo("aodoo/rust-cnb".to_string()).await {
        Ok(repo) => println!("仓库信息: {:?}", repo),
        Err(ApiError::HttpError(404)) => println!("仓库不存在"),
        Err(ApiError::HttpError(403)) => println!("没有访问权限"),
        Err(ApiError::RequestError(e)) => println!("网络请求失败: {}", e),
        Err(e) => println!("其他错误: {}", e),
    }
}
```

## 依赖项

此 SDK 使用以下核心依赖：

- `reqwest` - HTTP 客户端
- `tokio` - 异步运行时
- `serde` / `serde_json` - JSON 序列化/反序列化
- `url` - URL 解析
- `anyhow` - 错误处理

## 贡献

欢迎提交 Issue 和 Pull Request！

- 仓库地址: [https://cnb.cool/aodoo/rust-cnb](https://cnb.cool/aodoo/rust-cnb)

## 许可证

本项目采用 [MIT License](LICENSE) 开源协议。

## 相关链接

- [CNB 官网](https://cnb.cool)
- [CNB API 文档](https://api.cnb.cool)