# net-gitee

**Repository Path**: w9/net-gitee

## Basic Information

- **Project Name**: net-gitee
- **Description**: net-gitee is the .Net/C# SDK of Gitee OpenAPI.

特别感谢：
https://gitee.com/GitGroup/Gitee.VisualStudio
https://gitee.com/GitGroup/extension-docs
https://github.com/niltor/open-pdd-net-sdk
- **Primary Language**: C#
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 36
- **Forks**: 7
- **Created**: 2021-02-15
- **Last Updated**: 2026-07-18

## Categories & Tags

**Categories**: web-dev-toolkits

**Tags**: None

## README

# Leo.GiteeOpenSdk.V5

[![license](https://img.shields.io/badge/license-Apache--2.0-yellow)](LICENSE)
[![NuGet prerelease](https://img.shields.io/nuget/vpre/Leo.GiteeOpenSdk.V5)](https://www.nuget.org/packages/Leo.GiteeOpenSdk.V5)

面向 Gitee OpenAPI V5 的现代 .NET SDK。当前代码固定基于官方 V5 `5.4.92` 规范，覆盖 16 个分类、175 条路径和 264 个操作，同时面向 `netstandard2.0` 与 `net10.0`。

新包与旧的 `Leo.GiteeOpenSdk` 并行发布，命名空间为 `Leo.GiteeOpenSdk.V5`。旧包已冻结并在 NuGet 标记为 deprecated，替代包指向本包；迁移说明见 [docs/MIGRATION.md](docs/MIGRATION.md)。

## 安装

当前源码与本地候选包版本为 `1.0.0`：

```bash
dotnet add package Leo.GiteeOpenSdk.V5 --version 1.0.0
```

本地开发也可以直接引用 `src/GiteeOpenSdk.V5/GiteeOpenSdk.V5.csproj`。

## 依赖注入

```csharp
using Leo.GiteeOpenSdk.V5.Api;

builder.Services.AddGiteeOpenApiV5(options =>
{
    options.AccessToken = builder.Configuration["Gitee:AccessToken"];
    options.Timeout = TimeSpan.FromSeconds(30);
});

public sealed class CurrentUserService(IUsersApi users)
{
    public async Task<string?> GetLoginAsync(CancellationToken cancellationToken)
    {
        var response = await users.GetV5UserAsync(cancellationToken);
        return response.Ok().Login;
    }
}
```

`BaseAddress` 默认为 `https://gitee.com/api`。访问令牌可选；配置后由统一 provider 作为 `access_token` query 参数注入，未配置时不会发送空参数，因此公开资源可以匿名读取。需要认证的接口会保留 Gitee 返回的标准错误。不要把令牌写入日志、源码或配置仓库。

Beta.2 可以按 API 组或 OAuth 客户端配置标准 HTTP 管线，不需要依赖内部命名字符串：

```csharp
builder.Services.ConfigureGiteeOpenApiV5HttpClients(clients =>
{
    clients.For<IRepositoriesApi>().AddHttpMessageHandler<RequestMetricsHandler>();
    clients.OAuth.AddHttpMessageHandler<OAuthAuditHandler>();
});
```

## 不使用依赖注入

```csharp
using Leo.GiteeOpenSdk.V5;

using var gitee = new GiteeClient(options =>
{
    options.AccessToken = Environment.GetEnvironmentVariable("GITEE_TOKEN");
});

var response = await gitee.Repositories.GetV5ReposOwnerRepoAsync(
    "owner", "repository", cancellationToken);
var repository = response.Ok();
```

需要自定义代理、测试 handler 或传输策略时，可提供每次返回新实例的 handler factory；原有简单构造函数保持不变：

```csharp
using var gitee = new GiteeClient(
    () => new SocketsHttpHandler { Proxy = configuredProxy },
    options => options.AccessToken = Environment.GetEnvironmentVariable("GITEE_TOKEN"));
```

`GiteeClient` 暴露 Activity、Checks、Emails、Enterprises、Gists、GitData、Issues、Labels、Milestones、Miscellaneous、Organizations、PullRequests、Repositories、Search、Users、Webhooks 共 16 组接口。

## 响应、分页与错误

网络方法均为异步并接受 `CancellationToken`。返回值保留状态码、`Headers`、`ContentHeaders`、`RawContent`、请求 URI 与请求耗时，因此分页头和限流头不会丢失：

```csharp
var response = await issues.GetV5ReposOwnerRepoIssuesAsync(
    "owner", "repository", cancellationToken: cancellationToken);

var issuesOnPage = response.Ok();
var nextPage = response.Headers.TryGetValues("Link", out var links)
    ? links.SingleOrDefault()
    : null;
```

非 2xx、传输失败和 OAuth 错误统一使用 `GiteeApiException`。异常包含 `StatusCode`、响应头、非 JSON 原始错误体和请求 ID；异常中的 `access_token` 会脱敏。429 的 `Retry-After` 与 `X-RateLimit-*` 头原样保留。

```csharp
try
{
    await users.GetV5UserAsync(cancellationToken);
}
catch (GiteeApiException exception) when (exception.StatusCode == HttpStatusCode.TooManyRequests)
{
    var retryAfter = exception.Headers.GetValueOrDefault("Retry-After");
}
```

SDK 不默认重试写操作。DI 应用可以使用 `ConfigureHttpClientDefaults` 配置共同管线，或使用 `ConfigureGiteeOpenApiV5HttpClients` 精确配置单个 API 组；增加重试前必须确认目标组不会执行不应重试的写操作。

## OAuth

OAuth token 端点不在 V5 OpenAPI 文档内，由手写客户端覆盖：

```csharp
var token = await gitee.OAuth.ExchangeCodeAsync(
    code,
    clientId,
    clientSecret,
    new Uri("https://app.example/oauth/callback"),
    cancellationToken);

var refreshed = await gitee.OAuth.RefreshTokenAsync(
    token.RefreshToken!, clientId, clientSecret, cancellationToken);
```

## Webhook

`GiteeWebhookVerifier` 使用 HMAC-SHA256、固定时间比较和 `TimeProvider`。默认只接受与当前时间相差不超过一小时的毫秒时间戳：

```csharp
var push = JsonSerializer.Deserialize<GiteeWebhookPushEvent>(requestBody);
var verifier = new GiteeWebhookVerifier();
if (push is null || !verifier.Verify(webhookSecret, push))
    return Results.Unauthorized();
```

模型通过 `JsonExtensionData` 保留未来新增字段，已包含通用、Push、Issue 和 Note 事件的稳定外壳。

## 可运行示例

[`samples/GiteeOpenSdk.V5.Examples`](samples/GiteeOpenSdk.V5.Examples) 提供 DI、非 DI、分页、错误、OAuth 和 Webhook 的完整控制台示例。API 示例全部只读；敏感值只读取环境变量。

```bash
dotnet run --project samples/GiteeOpenSdk.V5.Examples -- --help
dotnet run --project samples/GiteeOpenSdk.V5.Examples -- repository w9 net-gitee
dotnet run --project samples/GiteeOpenSdk.V5.Examples -- repository-di w9 net-gitee
dotnet run --project samples/GiteeOpenSdk.V5.Examples -- issues w9 net-gitee 1
```

六类场景的真实运行结果与 Beta.2 增量 API 决策见 [消费者使用体验审查](docs/CONSUMER_EXPERIENCE_REVIEW.md)，服务端缺字段、未知字段与 `null` 的处理边界见 [Beta.2 模型兼容审计](docs/MODEL_COMPATIBILITY_AUDIT.md)。

## 开发与生成

需要 .NET 10 SDK、Node.js、Java 和 Bash。

```bash
./eng/openapi/generate-v5.sh
./eng/verify-generated.sh
dotnet test net-gitee.slnx -c Release
dotnet pack src/GiteeOpenSdk.V5/GiteeOpenSdk.V5.csproj -c Release

# 显式访问真实 Gitee，只执行读取操作
GITEE_LIVE_TESTS=1 ./eng/live-smoke-v5.sh
```

生成文件禁止直接修改。官方原始规范、SHA-256、规范化结果和每条修正规则都保存在 `openapi/v5`；完整维护流程见 [docs/CODEGEN.md](docs/CODEGEN.md)，真实环境测试的范围与安全约束见 [docs/LIVE_SMOKE.md](docs/LIVE_SMOKE.md)。

## 版本路线

- `1.0.0-alpha.1`：全量生成、规范修正、认证、统一错误和基础契约测试。
- `1.0.0-beta.1`：真实接口审计、公共 API 冻结、OAuth、Webhook、迁移文档和发布验证。
- `1.0.0-beta.2`：消费者体验增强、完整程序集 API 基线和模型兼容审计。
- `1.0.0`：264 个操作的可复现生成与完整安装验证。

完整待办见 [docs/ROADMAP.md](docs/ROADMAP.md)，公共 API 冻结审查见 [docs/PUBLIC_API_FREEZE.md](docs/PUBLIC_API_FREEZE.md)。当前包对应官方社区开发者 V5；官方企业开发者 V8 使用独立规范、地址和包边界，详见 [docs/PRODUCT_BOUNDARIES.md](docs/PRODUCT_BOUNDARIES.md)。Socket 和 Issue → 分支 → PR 上层自动化同样不属于 V5 首期。

## 安全

仓库已移除旧 Sample 中的 ClientId、OAuth code、企业与仓库示例信息，但未改写公开 Git 历史。历史 Gitee OAuth 应用 `fOS` 已于 2026-07-17 删除；其他从历史复制出的 token 或 secret 仍不得复用。安全报告与凭据处置记录见 [SECURITY.md](SECURITY.md)。

本项目使用 [Apache-2.0](LICENSE) 许可证。

## 发布与支持

`1.0.0` 处于发布准备中。`1.0.0-beta.2` 已发布到 [NuGet](https://www.nuget.org/packages/Leo.GiteeOpenSdk.V5/1.0.0-beta.2)，对应 [Gitee Release](https://gitee.com/w9/net-gitee/releases/tag/v1.0.0-beta.2)；哈希、签名与公共源双目标安装结果见 [Beta.2 发布验证记录](docs/RELEASE_1.0.0-beta.2.md)。上一版 [Beta.1 发布验证记录](docs/RELEASE_1.0.0-beta.1.md) 继续保留。旧 `Leo.GiteeOpenSdk` 0.3.0 已标记为 deprecated，弃用原因、迁移说明和替代包均已登记。

每次发布必须通过 `./eng/ci.sh`，并使用已打包且通过双目标消费者测试的 `.nupkg`。流水线会检查包内容、符号包、仓库提交和 SHA-256 发布清单；发布流程见 [docs/RELEASING.md](docs/RELEASING.md)。发布后需从公共 NuGet 源验证包页面、依赖、README 和消费者项目恢复。

`1.0.0-beta.2` 仍属于预发布版本，但 264 个社区 V5 主操作保持冻结。兼容修复可以直接进入；新增公共 API 必须更新冻结清单并说明理由；破坏性变化必须提供迁移说明并提升预发布版本。发现生成规范缺陷时请提交可复现样例，不要直接修改 `Generated` 目录。