Leo.GiteeOpenSdk.V5 1.0.1

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。

安装

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

dotnet add package Leo.GiteeOpenSdk.V5 --version 1.0.1

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

依赖注入

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 管线，不需要依赖内部命名字符串：

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

不使用依赖注入

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；原有简单构造函数保持不变：

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 与请求耗时，因此分页头和限流头不会丢失：

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-* 头原样保留。

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 文档内，由手写客户端覆盖：

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。默认只接受与当前时间相差不超过一小时的毫秒时间戳：

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 提供 DI、非 DI、分页、错误、OAuth 和 Webhook 的完整控制台示例。API 示例全部只读；敏感值只读取环境变量。

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 决策见 消费者使用体验审查，服务端缺字段、未知字段与 null 的处理边界见 Beta.2 模型兼容审计。

开发与生成

需要 .NET 10 SDK、Node.js、Java 和 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/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，公共 API 冻结审查见 docs/PUBLIC_API_FREEZE.md。当前包对应官方社区开发者 V5；官方企业开发者 V8 使用独立规范、地址和包边界，详见 docs/PRODUCT_BOUNDARIES.md。Socket 和 Issue → 分支 → PR 上层自动化同样不属于 V5 首期。

安全

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

本项目使用 Apache-2.0 许可证。

发布与支持

1.0.1 已备齐发布产物与发布验证材料，待发布到 NuGet 与 Gitee Release；本地验证与发布记录见 1.0.1 发布验证记录。
1.0.0 已发布到 NuGet，对应 Gitee Release；哈希、签名与公共源双目标安装结果见 1.0.0 发布验证记录。
1.0.0-beta.2 已发布到 NuGet，对应 Gitee Release；哈希、签名与公共源双目标安装结果见 Beta.2 发布验证记录。上一版 Beta.1 发布验证记录 继续保留。旧 Leo.GiteeOpenSdk 0.3.0 已标记为 deprecated，弃用原因、迁移说明和替代包均已登记。

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

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