在 .NET Core WebAPI 开发中，REST API 是一种架构风格，用于构建基于 HTTP 协议的 Web 服务。它遵循 REST（Representational State Transfer）设计原则。

核心概念

1. RESTful 原则

• 统一接口：使用标准 HTTP 方法（GET、POST、PUT、DELETE 等）
• 无状态：每个请求都包含处理所需的所有信息
• 资源导向：一切都是资源，通过 URI 标识
• 可缓存：响应应定义是否可缓存
• 分层系统：客户端不关心与最终服务器的中间层

2. 在 .NET Core WebAPI 中的实现

// 典型的 REST API Controller
[ApiController]
[Route("api/[controller]")]  // 资源路径：api/products
public class ProductsController : ControllerBase
{
    private readonly IProductService _productService;
    
    public ProductsController(IProductService productService)
    {
        _productService = productService;
    }
    
    // GET api/products - 获取所有产品
    [HttpGet]
    public async Task<ActionResult<IEnumerable<ProductDto>>> GetProducts()
    {
        var products = await _productService.GetAllAsync();
        return Ok(products);  // HTTP 200 OK
    }
    
    // GET api/products/{id} - 获取单个产品
    [HttpGet("{id}")]
    public async Task<ActionResult<ProductDto>> GetProduct(int id)
    {
        var product = await _productService.GetByIdAsync(id);
        
        if (product == null)
            return NotFound();  // HTTP 404 Not Found
        
        return Ok(product);  // HTTP 200 OK
    }
    
    // POST api/products - 创建新产品
    [HttpPost]
    public async Task<ActionResult<ProductDto>> CreateProduct(CreateProductDto dto)
    {
        var createdProduct = await _productService.CreateAsync(dto);
        
        // RESTful 标准：返回 201 Created 和资源位置
        return CreatedAtAction(
            nameof(GetProduct),
            new { id = createdProduct.Id },
            createdProduct);  // HTTP 201 Created
    }
    
    // PUT api/products/{id} - 更新整个产品
    [HttpPut("{id}")]
    public async Task<IActionResult> UpdateProduct(int id, UpdateProductDto dto)
    {
        var result = await _productService.UpdateAsync(id, dto);
        
        if (!result)
            return NotFound();
            
        return NoContent();  // HTTP 204 No Content
    }
    
    // PATCH api/products/{id} - 部分更新产品
    [HttpPatch("{id}")]
    public async Task<IActionResult> PartialUpdateProduct(int id, JsonPatchDocument<UpdateProductDto> patchDoc)
    {
        // 部分更新逻辑
        return NoContent();
    }
    
    // DELETE api/products/{id} - 删除产品
    [HttpDelete("{id}")]
    public async Task<IActionResult> DeleteProduct(int id)
    {
        var result = await _productService.DeleteAsync(id);
        
        if (!result)
            return NotFound();
            
        return NoContent();  // HTTP 204 No Content
    }
}

3. HTTP 方法与操作对应关系

4. 状态码使用

// 常用 HTTP 状态码
return Ok(data);                    // 200 - 成功
return Created(uri, data);          // 201 - 创建成功
return NoContent();                 // 204 - 成功无内容
return BadRequest(error);           // 400 - 客户端错误
return Unauthorized();              // 401 - 未认证
return Forbid();                    // 403 - 无权限
return NotFound();                  // 404 - 资源不存在
return Conflict(error);             // 409 - 冲突
return StatusCode(500, error);      // 500 - 服务器错误

5. RESTful 最佳实践

// 1. 使用复数名词命名资源
// 正确：/api/products、/api/users
// 避免：/api/getProduct、/api/createUser

// 2. 使用嵌套资源表示关系
[HttpGet("api/users/{userId}/orders")]  // 获取用户的订单
public IActionResult GetUserOrders(int userId) { }

// 3. 使用查询参数进行过滤、分页、排序
[HttpGet("api/products")]
public IActionResult GetProducts(
    [FromQuery] string category,      // 过滤
    [FromQuery] int page = 1,         // 分页
    [FromQuery] int pageSize = 10,    // 分页大小
    [FromQuery] string sortBy = "name") { }

// 4. 使用 HATEOAS 提供超媒体链接
public class ProductDto
{
    public int Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
    
    public List<LinkDto> Links { get; set; } = new();
}

// 在控制器中添加链接
productDto.Links.Add(new LinkDto(
    href: Url.Link("GetProduct", new { id = productDto.Id }),
    rel: "self",
    method: "GET"));

6. .NET Core 中的配置

// Startup.cs 或 Program.cs 中的配置
builder.Services.AddControllers()
    .AddJsonOptions(options =>
    {
        options.JsonSerializerOptions.PropertyNamingPolicy = JsonNamingPolicy.CamelCase;
    })
    .ConfigureApiBehaviorOptions(options =>
    {
        // 自动验证模型
        options.SuppressModelStateInvalidFilter = false;
    });

// 添加 Swagger/OpenAPI 文档（推荐）
builder.Services.AddEndpointsApiExplorer();
builder.Services.AddSwaggerGen();

7. 版本控制

// 使用 URL 版本控制
[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/[controller]")]
public class ProductsController : ControllerBase { }

// 或使用 Header 版本控制
[ApiVersion("2.0")]
[Route("api/[controller]")]
public class ProductsV2Controller : ControllerBase { }

总结

在 .NET Core WebAPI 中，REST API 是：

1. 基于 HTTP 标准的 Web 服务架构
2. 资源导向的设计方式
3. 无状态的通信协议
4. 使用标准 HTTP 方法对应 CRUD 操作
5. 返回标准 HTTP 状态码
6. 支持内容协商（JSON/XML）
7. 易于缓存和扩展

这样的设计使得 API 具有：

• 可发现性：清晰的 URL 结构
• 可读性：直观的 HTTP 方法和状态码
• 松耦合：客户端和服务器独立演化
• 可扩展性：易于添加新功能
• 标准化：符合行业最佳实践

REST API 是现代微服务架构和前后端分离应用的基础通信方式。