dotnet-webapi

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

.NET 10 Web API Development

.NET 10 Web API开发

Build production-ready ASP.NET Core Web APIs with .NET 10 using best practices from 2025.

使用.NET 10结合2025年最佳实践构建生产级ASP.NET Core Web API。

Quick Start

快速开始

Create a new Web API project:

bash

scripts/new_api.sh <project_name> [output_directory]

Example:

bash

scripts/new_api.sh ProductsApi
cd ProductsApi
dotnet build
dotnet run --project ProductsApi.Api

This creates:

Solution with API and Test projects
Controller-based Web API (.NET 10)
xUnit test project with integration testing setup
Proper folder structure (Controllers, Models, Services)
.gitignore configured for .NET

创建新的Web API项目：

bash

scripts/new_api.sh <project_name> [output_directory]

示例：

bash

scripts/new_api.sh ProductsApi
cd ProductsApi
dotnet build
dotnet run --project ProductsApi.Api

这将创建：

包含API和测试项目的解决方案
基于控制器的Web API（.NET 10）
已配置集成测试的xUnit测试项目
规范的文件夹结构（Controllers、Models、Services）
针对.NET配置的.gitignore

Core Features

核心功能

1. Project Scaffolding

1. 项目脚手架

Create New API Project:

bash

scripts/new_api.sh MyApi ./projects

Generates:

```
MyApi.Api
```
- Main API project with controllers
```
MyApi.Tests
```
- xUnit test project with integration testing
Solution file linking both projects
Standard folder structure
Test dependencies (FluentAssertions, WebApplicationFactory)

创建新API项目：

bash

scripts/new_api.sh MyApi ./projects

生成内容：

```
MyApi.Api
```
- 包含控制器的主API项目
```
MyApi.Tests
```
- 带有集成测试设置的xUnit测试项目
关联两个项目的解决方案文件
标准文件夹结构
测试依赖项（FluentAssertions、WebApplicationFactory）

2. Add CRUD Entities

2. 添加CRUD实体

Generate Entity with Controller and Service:

bash

scripts/add_entity.sh <entity_name> <project_path>

Example:

bash

scripts/add_entity.sh Product ./MyApi
scripts/add_entity.sh Customer ./MyApi

Generates for each entity:

Model class (
```
Models/Product.cs
```
)
Service interface (
```
Services/IProductService.cs
```
)
Service implementation (
```
Services/ProductService.cs
```
)
CRUD controller (
```
Controllers/ProductController.cs
```
)
Automatic service registration in DI container

API Endpoints Created:

GET    /api/Product        - Get all
GET    /api/Product/{id}   - Get by ID
POST   /api/Product        - Create
PUT    /api/Product/{id}   - Update
DELETE /api/Product/{id}   - Delete

生成包含控制器和服务的实体：

bash

scripts/add_entity.sh <entity_name> <project_path>

示例：

bash

scripts/add_entity.sh Product ./MyApi
scripts/add_entity.sh Customer ./MyApi

为每个实体生成：

模型类（
```
Models/Product.cs
```
）
服务接口（
```
Services/IProductService.cs
```
）
服务实现（
```
Services/ProductService.cs
```
）
CRUD控制器（
```
Controllers/ProductController.cs
```
）
在DI容器中自动注册服务

创建的API端点：

GET    /api/Product        - 获取全部
GET    /api/Product/{id}   - 根据ID获取
POST   /api/Product        - 创建
PUT    /api/Product/{id}   - 更新
DELETE /api/Product/{id}   - 删除

3. Package Management

3. 包管理

Add NuGet Packages:

bash

scripts/add_package.sh <project_path> <package_name|preset>

Presets:

bash

undefined

添加NuGet包：

bash

scripts/add_package.sh <project_path> <package_name|preset>

预设选项：

bash

undefined

Entity Framework with PostgreSQL

带PostgreSQL的Entity Framework

scripts/add_package.sh ./MyApi ef-postgres

Entity Framework with SQL Server

带SQL Server的Entity Framework

scripts/add_package.sh ./MyApi ef-sqlserver

JWT Authentication

JWT认证

scripts/add_package.sh ./MyApi auth

FluentValidation

FluentValidation验证

scripts/add_package.sh ./MyApi validation

Individual package

单个包

scripts/add_package.sh ./MyApi Newtonsoft.Json

undefined

scripts/add_package.sh ./MyApi Newtonsoft.Json

undefined

4. Docker Support

4. Docker支持

Generate Dockerfile and docker-compose:

bash

scripts/generate_dockerfile.sh <project_path>

Example:

bash

scripts/generate_dockerfile.sh ./MyApi

Generates:

Multi-stage optimized Dockerfile
docker-compose.yml with PostgreSQL
.dockerignore
Non-root user configuration
Health check setup

Build and run:

bash

docker-compose up -d
docker-compose logs -f api

生成Dockerfile和docker-compose：

bash

scripts/generate_dockerfile.sh <project_path>

示例：

bash

scripts/generate_dockerfile.sh ./MyApi

生成内容：

多阶段优化的Dockerfile
包含PostgreSQL的docker-compose.yml
.dockerignore
非root用户配置
健康检查设置

构建并运行：

bash

docker-compose up -d
docker-compose logs -f api

.NET 10 Features

.NET 10特性

Built-in Features

内置特性

OpenAPI 3.1 Support:

csharp

// Program.cs
builder.Services.AddOpenApi();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi(); // /openapi/v1.json
}

Automatic Minimal API Validation: DataAnnotations are automatically validated in .NET 10 for Minimal APIs and controllers.

Output Caching:

csharp

builder.Services.AddOutputCache();
app.UseOutputCache();

[OutputCache(Duration = 300)]
[HttpGet]
public async Task<IActionResult> GetAll()

Rate Limiting:

csharp

builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("api", config =>
    {
        config.PermitLimit = 100;
        config.Window = TimeSpan.FromMinutes(1);
    });
});

OpenAPI 3.1支持：

csharp

// Program.cs
builder.Services.AddOpenApi();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi(); // /openapi/v1.json
}

自动极简API验证： 在.NET 10中，DataAnnotations会自动对极简API和控制器进行验证。

输出缓存：

csharp

builder.Services.AddOutputCache();
app.UseOutputCache();

[OutputCache(Duration = 300)]
[HttpGet]
public async Task<IActionResult> GetAll()

速率限制：

csharp

builder.Services.AddRateLimiter(options =>
{
    options.AddFixedWindowLimiter("api", config =>
    {
        config.PermitLimit = 100;
        config.Window = TimeSpan.FromMinutes(1);
    });
});

C# 14.0 Features

C# 14.0特性

Use latest C# features:

Primary constructors
Collection expressions
Required members
Init-only properties

使用最新C#特性：

主构造函数
集合表达式
必填成员
仅初始化属性

Development Workflows

开发工作流

Typical Development Flow

典型开发流程

Create project:

bash

scripts/new_api.sh OrderService
cd OrderService

Add entities:

bash

scripts/add_entity.sh Order .
scripts/add_entity.sh OrderItem .

Add database:
bash
```
scripts/add_package.sh . ef-postgres
```

Build and run:

bash

dotnet build
dotnet run --project OrderService.Api

Test:
bash
```
dotnet test
```

Dockerize:

bash

scripts/generate_dockerfile.sh .
docker-compose up

创建项目：

bash

scripts/new_api.sh OrderService
cd OrderService

添加实体：

bash

scripts/add_entity.sh Order .
scripts/add_entity.sh OrderItem .

添加数据库：
bash
```
scripts/add_package.sh . ef-postgres
```

构建并运行：

bash

dotnet build
dotnet run --project OrderService.Api

测试：
bash
```
dotnet test
```

容器化：

bash

scripts/generate_dockerfile.sh .
docker-compose up

Entity Framework Integration

Entity Framework集成

After adding EF packages, configure DbContext:

csharp

// Data/ApplicationDbContext.cs
public class ApplicationDbContext : DbContext
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options) { }

    public DbSet<Product> Products => Set<Product>();
}

// Program.cs
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));

// appsettings.json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=mydb;Username=postgres;Password=postgres"
  }
}

Run migrations:

bash

dotnet ef migrations add Initial --project MyApi.Api
dotnet ef database update --project MyApi.Api

添加EF包后，配置DbContext：

csharp

// Data/ApplicationDbContext.cs
public class ApplicationDbContext : DbContext
{
    public ApplicationDbContext(DbContextOptions<ApplicationDbContext> options)
        : base(options) { }

    public DbSet<Product> Products => Set<Product>();
}

// Program.cs
builder.Services.AddDbContext<ApplicationDbContext>(options =>
    options.UseNpgsql(builder.Configuration.GetConnectionString("DefaultConnection")));

// appsettings.json
{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Database=mydb;Username=postgres;Password=postgres"
  }
}

运行迁移：

bash

dotnet ef migrations add Initial --project MyApi.Api
dotnet ef database update --project MyApi.Api

Authentication Setup

认证设置

After adding auth package:

csharp

// Program.cs
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]))
        };
    });

app.UseAuthentication();
app.UseAuthorization();

// Protect endpoints
[Authorize]
[HttpGet("admin")]
public IActionResult AdminOnly() => Ok("Admin data");

添加auth包后：

csharp

// Program.cs
builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddJwtBearer(options =>
    {
        options.TokenValidationParameters = new TokenValidationParameters
        {
            ValidateIssuer = true,
            ValidateAudience = true,
            ValidateLifetime = true,
            ValidateIssuerSigningKey = true,
            ValidIssuer = builder.Configuration["Jwt:Issuer"],
            ValidAudience = builder.Configuration["Jwt:Audience"],
            IssuerSigningKey = new SymmetricSecurityKey(
                Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]))
        };
    });

app.UseAuthentication();
app.UseAuthorization();

// 保护端点
[Authorize]
[HttpGet("admin")]
public IActionResult AdminOnly() => Ok("Admin data");

Best Practices

最佳实践

Controller Pattern

控制器模式

Generated controllers follow best practices:

csharp

[ApiController]
[Route("api/[controller]")]
public class ProductController : ControllerBase
{
    private readonly IProductService _service;
    private readonly ILogger<ProductController> _logger;

    // Constructor injection
    public ProductController(
        IProductService service,
        ILogger<ProductController> logger)
    {
        _service = service;
        _logger = logger;
    }

    // Documented endpoints
    /// <summary>
    /// Get all products
    /// </summary>
    [HttpGet]
    [ProducesResponseType(StatusCodes.Status200OK)]
    public async Task<ActionResult<IEnumerable<Product>>> GetAll()

    // Proper status codes
    [HttpPost]
    [ProducesResponseType(StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public async Task<ActionResult<Product>> Create(Product entity)
    {
        var created = await _service.CreateAsync(entity);
        return CreatedAtAction(nameof(GetById), new { id = created.Id }, created);
    }
}

生成的控制器遵循最佳实践：

csharp

[ApiController]
[Route("api/[controller]")]
public class ProductController : ControllerBase
{
    private readonly IProductService _service;
    private readonly ILogger<ProductController> _logger;

    // 构造函数注入
    public ProductController(
        IProductService service,
        ILogger<ProductController> logger)
    {
        _service = service;
        _logger = logger;
    }

    // 带文档的端点
    /// <summary>
    /// 获取全部产品
    /// </summary>
    [HttpGet]
    [ProducesResponseType(StatusCodes.Status200OK)]
    public async Task<ActionResult<IEnumerable<Product>>> GetAll()

    // 规范的状态码
    [HttpPost]
    [ProducesResponseType(StatusCodes.Status201Created)]
    [ProducesResponseType(StatusCodes.Status400BadRequest)]
    public async Task<ActionResult<Product>> Create(Product entity)
    {
        var created = await _service.CreateAsync(entity);
        return CreatedAtAction(nameof(GetById), new { id = created.Id }, created);
    }
}

Service Layer Pattern

服务层模式

csharp

// Interface
public interface IProductService
{
    Task<IEnumerable<Product>> GetAllAsync();
    Task<Product?> GetByIdAsync(int id);
    Task<Product> CreateAsync(Product entity);
    Task<Product?> UpdateAsync(int id, Product entity);
    Task<bool> DeleteAsync(int id);
}

// Implementation with business logic
public class ProductService : IProductService
{
    // In-memory for demo, replace with repository/DbContext
    private readonly List<Product> _entities = new();

    public async Task<Product> CreateAsync(Product entity)
    {
        entity.Id = _nextId++;
        entity.CreatedAt = DateTime.UtcNow;
        _entities.Add(entity);
        return entity;
    }
}

csharp

// 接口
public interface IProductService
{
    Task<IEnumerable<Product>> GetAllAsync();
    Task<Product?> GetByIdAsync(int id);
    Task<Product> CreateAsync(Product entity);
    Task<Product?> UpdateAsync(int id, Product entity);
    Task<bool> DeleteAsync(int id);
}

// 包含业务逻辑的实现
public class ProductService : IProductService
{
    // 演示用内存存储，可替换为仓储/DbContext
    private readonly List<Product> _entities = new();

    public async Task<Product> CreateAsync(Product entity)
    {
        entity.Id = _nextId++;
        entity.CreatedAt = DateTime.UtcNow;
        _entities.Add(entity);
        return entity;
    }
}

Testing

测试

Generated test projects include integration testing setup:

csharp

public class ProductsEndpointTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public ProductsEndpointTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task GetAll_ReturnsSuccessStatusCode()
    {
        var response = await _client.GetAsync("/api/products");
        response.EnsureSuccessStatusCode();
    }
}

Run tests:

bash

dotnet test
dotnet test --logger "console;verbosity=detailed"

生成的测试项目包含集成测试设置：

csharp

public class ProductsEndpointTests : IClassFixture<WebApplicationFactory<Program>>
{
    private readonly HttpClient _client;

    public ProductsEndpointTests(WebApplicationFactory<Program> factory)
    {
        _client = factory.CreateClient();
    }

    [Fact]
    public async Task GetAll_ReturnsSuccessStatusCode()
    {
        var response = await _client.GetAsync("/api/products");
        response.EnsureSuccessStatusCode();
    }
}

运行测试：

bash

dotnet test
dotnet test --logger "console;verbosity=detailed"

References

参考资料

For detailed guidance, see:

如需详细指导，请查看：

API Best Practices

API最佳实践

references/api_best_practices.md

- Comprehensive guide covering:

RESTful API design
HTTP status codes
Error handling patterns
Validation strategies
Authentication & authorization
Dependency injection
Logging best practices
Performance optimization
OpenAPI documentation

references/api_best_practices.md

- 综合指南涵盖：

RESTful API设计
HTTP状态码
错误处理模式
验证策略
认证与授权
依赖注入
日志最佳实践
性能优化
OpenAPI文档

Testing Patterns

测试模式

references/testing_patterns.md

- Testing guide including:

xUnit fundamentals
Unit testing with Moq
Integration testing with WebApplicationFactory
Test data builders
FluentAssertions usage
Common testing patterns

references/testing_patterns.md

- 测试指南包括：

xUnit基础
结合Moq的单元测试
结合WebApplicationFactory的集成测试
测试数据构建器
FluentAssertions使用
常见测试模式

Common Packages

常用包

references/common_packages.md

- NuGet package guide for:

Database providers (EF Core, Dapper)
Authentication (JWT, Identity)
Validation (FluentValidation)
Testing tools (xUnit, Moq, FluentAssertions)
Logging (Serilog)
Utilities (AutoMapper, MediatR, Polly)

references/common_packages.md

- NuGet包指南涵盖：

数据库提供程序（EF Core、Dapper）
认证（JWT、Identity）
验证（FluentValidation）
测试工具（xUnit、Moq、FluentAssertions）
日志（Serilog）
工具库（AutoMapper、MediatR、Polly）

Common Scenarios

常见场景

Scenario 1: New CRUD API

场景1：新建CRUD API

bash

undefined

bash

undefined

Create project

创建项目

scripts/new_api.sh InventoryApi

Add entities

添加实体

scripts/add_entity.sh Product ./InventoryApi scripts/add_entity.sh Category ./InventoryApi

Add database

添加数据库

scripts/add_package.sh ./InventoryApi ef-postgres

Run

运行

cd InventoryApi dotnet run --project InventoryApi.Api

undefined

cd InventoryApi dotnet run --project InventoryApi.Api

undefined

Scenario 2: Microservice with Docker

场景2：带Docker的微服务

bash

undefined

bash

undefined

Create and setup

创建并配置

scripts/new_api.sh OrderService scripts/add_entity.sh Order ./OrderService scripts/add_package.sh ./OrderService ef-postgres scripts/generate_dockerfile.sh ./OrderService

Deploy

部署

cd OrderService docker-compose up -d

undefined

cd OrderService docker-compose up -d

undefined

Scenario 3: Authenticated API

场景3：带认证的API

bash

scripts/new_api.sh SecureApi
scripts/add_entity.sh User ./SecureApi
scripts/add_package.sh ./SecureApi auth
scripts/add_package.sh ./SecureApi validation

bash

scripts/new_api.sh SecureApi
scripts/add_entity.sh User ./SecureApi
scripts/add_package.sh ./SecureApi auth
scripts/add_package.sh ./SecureApi validation

Troubleshooting

故障排查

.NET SDK Not Found

.NET SDK未找到

Ensure .NET 10 SDK is installed:

bash

dotnet --version  # Should be 10.x

Install from: https://dotnet.microsoft.com/download/dotnet/10.0

确保已安装.NET 10 SDK：

bash

dotnet --version  # 应显示10.x

从以下地址安装：https://dotnet.microsoft.com/download/dotnet/10.0

Port Already in Use

端口已被占用

Change port in Properties/launchSettings.json or use environment variable:

bash

ASPNETCORE_HTTP_PORTS=5001 dotnet run --project MyApi.Api

在Properties/launchSettings.json中修改端口，或使用环境变量：

bash

ASPNETCORE_HTTP_PORTS=5001 dotnet run --project MyApi.Api

Docker Build Fails

Docker构建失败

Ensure Docker daemon is running:

bash

docker ps

Check Dockerfile paths match project structure.

确保Docker守护进程正在运行：

bash

docker ps

检查Dockerfile路径是否与项目结构匹配。

EF Migrations Fail

EF迁移失败

Ensure connection string is correct and database is accessible:

bash

dotnet ef database update --verbose --project MyApi.Api

确保连接字符串正确且数据库可访问：

bash

dotnet ef database update --verbose --project MyApi.Api

Integration with Other Skills

与其他技能集成

Works well with:

```
postgres-query
```
- Query databases created by your API
```
postgres-backup-restore
```
- Restore test data for development
```
ruby-rails
```
- Interop with Rails backends

可与以下技能良好配合：

```
postgres-query
```
- 查询由你的API创建的数据库
```
postgres-backup-restore
```
- 为开发恢复测试数据
```
ruby-rails
```
- 与Rails后端互操作

Summary

总结

This skill provides:

✅ Rapid project scaffolding ✅ CRUD entity generation ✅ NuGet package management ✅ Docker containerization ✅ .NET 10 best practices ✅ Testing setup included ✅ Production-ready code structure ✅ Comprehensive documentation

Start building modern Web APIs with .NET 10 today!

本技能提供：

✅ 快速项目脚手架 ✅ CRUD实体生成 ✅ NuGet包管理 ✅ Docker容器化 ✅ .NET 10最佳实践 ✅ 内置测试设置 ✅ 生产级代码结构 ✅ 全面的文档

立即使用.NET 10构建现代Web API！