C#如何写出健壮的API？ASP.NET Core API版本控制与文档生成（Swagger）

答案是输入验证、异常处理、日志记录、统一响应格式和版本控制为API健壮性设计关键点，结合Swagger实现文档自动化与多版本支持，提升可维护性和易用性。

API健壮性设计的关键点

写出健壮的C# API，核心在于稳定性、可维护性和易用性。ASP.NET Core提供了良好的基础支持，但需要合理设计才能应对真实场景。重点包括：输入验证、异常处理、日志记录、响应格式统一和版本控制。

使用 ModelState 验证请求数据，结合 Data Annotations 或 FluentValidation 提升准确性。全局异常过滤器（Exception Filter）捕获未处理异常，避免暴露敏感信息。通过中间件记录请求日志，便于排查问题。

返回结构统一的响应体，例如封装为 ApiResponse 类型，包含 code、message 和 data 字段，让前端更容易处理成功与错误情况。

API版本控制策略

随着业务演进，API需要迭代更新。直接修改旧接口会影响已有客户端，因此引入版本控制至关重要。

ASP.NET Core 支持多种方式：

• URL 路径版本：如 /api/v1/users、/api/v2/users，直观且易于调试
• 查询参数版本：如 /api/users?version=1.0，对路由影响小但不够规范
• 请求头版本控制：通过自定义Header传递版本号，适合内部系统

推荐使用 URL 路径方式，并配合 Microsoft.AspNetCore.Mvc.Versioning 包实现：

services.AddApiVersioning(options =>
{
    options.DefaultApiVersion = new ApiVersion(1, 0);
    options.AssumeDefaultVersionWhenUnspecified = true;
    options.ReportApiVersions = true;
});

在控制器上标注版本：

[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("1.0")]
public class UserController : ControllerBase
{
    // v1 实现
}
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
[ApiVersion("2.0")]
public class UserController : ControllerBase
{
// v2 实现
}

Swagger文档生成与多版本支持

Swagger（现称 OpenAPI）是API文档的事实标准。在 ASP.NET Core 中集成 Swashbuckle.AspNetCore 可自动生成交互式文档。

安装包：

dotnet add package Swashbuckle.AspNetCore

配置服务：

services.AddEndpointsApiExplorer();
services.AddSwaggerGen(c =>
{
    c.SwaggerDoc("v1", new OpenApiInfo { Title = "My API", Version = "v1" });
    c.SwaggerDoc("v2", new OpenApiInfo { Title = "My API", Version = "v2" });
});

启用中间件：

app.UseSwagger();
app.UseSwaggerUI(c =>
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "V1 Docs");
    c.SwaggerEndpoint("/swagger/v2/swagger.json", "V2 Docs");
});

结合 API 版本控制后，Swagger 会自动识别不同版本的控制器并分组展示。可通过 Tag 或命名空间进一步组织接口显示顺序。

添加 XML 注释增强文档可读性：

c.IncludeXmlComments(Path.Combine(AppContext.BaseDirectory, "YourApp.xml"));

在项目文件中启用生成：

  true
  1591

总结与最佳实践

构建健壮的 API 不仅是功能实现，更是长期维护的起点。合理使用版本控制避免破坏性变更，Swagger 提供清晰文档降低沟通成本。

建议：

• 所有接口启用模型验证
• 使用 API 版本控制预留扩展空间
• 每个版本都生成独立 Swagger 文档
• 添加响应示例和注释说明边界条件
• 生产环境关闭详细错误输出

基本上就这些，关键是在开发初期就把版本和文档当成必须项，而不是事后补救。