aspnet-api-standards

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ASP.NET Core API Standards

ASP.NET Core API 规范

CRITICAL DIRECTIVE

核心指令

ONLY implement what is explicitly requested. Do NOT add unrequested features like:

CORS configuration (unless asked for)
Swagger/OpenAPI setup (unless asked for)
Authentication/Authorization (unless asked for)
Rate limiting, caching, compression (unless asked for)
Additional middleware (unless asked for)

When user requests ONE thing (e.g., "create an exception filter"), implement ONLY that thing.

仅实现明确要求的功能。 请勿添加未被要求的功能，例如：

CORS配置（除非明确要求）
Swagger/OpenAPI配置（除非明确要求）
身份验证/授权（除非明确要求）
速率限制、缓存、压缩（除非明确要求）
额外中间件（除非明确要求）

当用户仅请求单一功能时（例如“创建一个异常过滤器”），仅实现该功能即可。

Core Controller Rules (ALWAYS Apply)

核心控制器规则（必须遵守）

Clean Controllers Pattern

简洁控制器模式

csharp

// REQUIRED structure
[ApiController]
[Route("api/[controller]")]
public class OrdersController(IMediator mediator) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> CreateOrder(
        [FromBody] CreateOrderCommand command,
        CancellationToken cancellationToken)
    {
        var result = await mediator.Send(command, cancellationToken);
        return CreatedAtAction(nameof(GetOrder), new { id = result }, result);
    }
}

MUST:

Inject ONLY
```
IMediator
```
(never repositories or domain services)
Use primary constructors
Include
```
CancellationToken
```
in all async methods
Apply
```
[ApiController]
```
attribute for automatic validation

NEVER:

Put business logic in controllers
Inject repositories directly
Use
```
.Result
```
,
```
.Wait()
```
, or
```
.GetAwaiter().GetResult()
```

csharp

// REQUIRED structure
[ApiController]
[Route("api/[controller]")]
public class OrdersController(IMediator mediator) : ControllerBase
{
    [HttpPost]
    public async Task<IActionResult> CreateOrder(
        [FromBody] CreateOrderCommand command,
        CancellationToken cancellationToken)
    {
        var result = await mediator.Send(command, cancellationToken);
        return CreatedAtAction(nameof(GetOrder), new { id = result }, result);
    }
}

必须遵守：

仅注入
```
IMediator
```
（绝不直接注入仓储或领域服务）
使用主构造函数
在所有异步方法中包含
```
CancellationToken
```
应用
```
[ApiController]
```
特性以启用自动验证

绝对禁止：

在控制器中编写业务逻辑
直接注入仓储
使用
```
.Result
```
、
```
.Wait()
```
或
```
.GetAwaiter().GetResult()
```

When to Read References

参考文档查阅场景

User asks about exception handling or error responses?
→ Read references/exception-handling.md

User asks about CORS, authentication, or authorization?
→ Read references/security.md

User asks about Swagger or API documentation?
→ Read references/swagger.md

User asks about middleware pipeline or Program.cs configuration?
→ Read references/middleware.md

用户询问异常处理或错误响应相关问题？
→ 查阅references/exception-handling.md

用户询问CORS、身份验证或授权相关问题？
→ 查阅references/security.md

用户询问Swagger或API文档相关问题？
→ 查阅references/swagger.md

用户询问中间件管道或Program.cs配置相关问题？
→ 查阅references/middleware.md

FluentValidation (Apply When Creating Commands/Queries)

FluentValidation（创建命令/查询时适用）

csharp

public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
{
    public CreateOrderCommandValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty().Must(items => items.Count <= 50);
    }
}

Register in Program.cs:

csharp

builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderCommandValidator>();
builder.Services.AddFluentValidationAutoValidation();

csharp

public class CreateOrderCommandValidator : AbstractValidator<CreateOrderCommand>
{
    public CreateOrderCommandValidator()
    {
        RuleFor(x => x.CustomerId).NotEmpty();
        RuleFor(x => x.Items).NotEmpty().Must(items => items.Count <= 50);
    }
}

在Program.cs中注册：

csharp

builder.Services.AddValidatorsFromAssemblyContaining<CreateOrderCommandValidator>();
builder.Services.AddFluentValidationAutoValidation();