跳到主要内容

API 分层

API 分层定义了控制器的组织方式、路由约定和认证策略。

控制器分组​

API 通过 [ApiExplorerSettings(GroupName = "...")] 和 [Area] 分组：

模块GroupNameArea说明
Identityidentityidentity身份认证
CmsKitcmscms内容管理
Platformplatplatform工具平台

控制器组织​

按功能分组​

Controllers/
├── Admin/           # 管理端 API
├── Community/       # 社区相关
├── Content/         # 内容相关
├── Discovery/       # 发现/搜索
├── Engagement/      # 互动（点赞、评论）
└── Governance/      # 治理（举报、审核）

按模块分组​

src/Services/
├── Identity/
│   └── Controllers/
│       ├── AccountController.cs
│       ├── UserController.cs
│       └── RoleController.cs
├── CmsKit/
│   └── Controllers/
│       ├── ArticleController.cs
│       ├── CommentController.cs
│       └── PollController.cs
└── Platform/
    └── Controllers/
        ├── TodoController.cs
        ├── ShortUrlController.cs
        └── DailyHotController.cs

路由约定​

基础路由​

[ApiController]
[Route("api/[module]/[controller]")]
public class ArticleController : FreeKitController
{
    // 路由: /api/cms/article
}

Area 路由​

[Area("identity")]
[ApiController]
[Route("api/identity/[controller]")]
public class UserController : FreeKitController
{
    // 路由: /api/identity/user
}

嵌套路由​

[ApiController]
[Route("api/cms/articles/{articleId}/comments")]
public class CommentController : FreeKitController
{
    // 路由: /api/cms/articles/{articleId}/comments
}

认证与权限​

认证策略​

// 需要登录
[Authorize]
public class ProtectedController : FreeKitController { }

// 需要管理员权限
[Authorize(Policy = "Admin")]
public class AdminController : FreeKitController { }

// 允许匿名
[AllowAnonymous]
public class PublicController : FreeKitController { }

权限策略​

// 自定义权限策略
[Authorize(Policy = "CmsKit.Articles")]
public class ArticleController : FreeKitController { }

// 多个权限
[Authorize(Policy = "CmsKit.Articles")]
[Authorize(Policy = "CmsKit.Comments")]
public class ArticleWithCommentsController : FreeKitController { }

请求/响应模型​

请求 DTO​

public class CreateArticleRequest
{
    [Required]
    [MaxLength(200)]
    public string Title { get; set; } = default!;

    [Required]
    public string Content { get; set; } = default!;

    public Guid? CategoryId { get; set; }
}

响应 DTO​

public class ArticleDto
{
    public Guid Id { get; set; }
    public string Title { get; set; } = default!;
    public string Content { get; set; } = default!;
    public DateTime CreateTime { get; set; }
}

版本控制​

[ApiVersion("1.0")]
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
public class ArticleV1Controller : FreeKitController { }

[ApiVersion("2.0")]
[ApiController]
[Route("api/v{version:apiVersion}/[controller]")]
public class ArticleV2Controller : FreeKitController { }

Swagger 配置​

builder.Services.AddSwaggerGen(options =>
{
    options.SwaggerDoc("v1", new OpenApiInfo
    {
        Title = "FreeKit API",
        Version = "v1"
    });

    options.DocInclusionPredicate((docName, apiDesc) =>
    {
        var routeValues = apiDesc.RouteValues;
        return routeValues.ContainsKey("controller");
    });
});

相关文档​