【REST API】-智慧文博士

在 .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/productspublicclassProductsController:ControllerBase{privatereadonlyIProductService_productService;publicProductsController(IProductServiceproductService){_productService=productService;}// GET api/products - 获取所有产品[HttpGet]publicasyncTask<ActionResult<IEnumerable<ProductDto>>>GetProducts(){varproducts=await_productService.GetAllAsync();returnOk(products);// HTTP 200 OK}// GET api/products/{id} - 获取单个产品[HttpGet("{id}")]publicasyncTask<ActionResult<ProductDto>>GetProduct(intid){varproduct=await_productService.GetByIdAsync(id);if(product==null)returnNotFound();// HTTP 404 Not FoundreturnOk(product);// HTTP 200 OK}// POST api/products - 创建新产品[HttpPost]publicasyncTask<ActionResult<ProductDto>>CreateProduct(CreateProductDtodto){varcreatedProduct=await_productService.CreateAsync(dto);// RESTful 标准：返回 201 Created 和资源位置returnCreatedAtAction(nameof(GetProduct),new{id=createdProduct.Id},createdProduct);// HTTP 201 Created}// PUT api/products/{id} - 更新整个产品[HttpPut("{id}")]publicasyncTask<IActionResult>UpdateProduct(intid,UpdateProductDtodto){varresult=await_productService.UpdateAsync(id,dto);if(!result)returnNotFound();returnNoContent();// HTTP 204 No Content}// PATCH api/products/{id} - 部分更新产品[HttpPatch("{id}")]publicasyncTask<IActionResult>PartialUpdateProduct(intid,JsonPatchDocument<UpdateProductDto>patchDoc){// 部分更新逻辑returnNoContent();}// DELETE api/products/{id} - 删除产品[HttpDelete("{id}")]publicasyncTask<IActionResult>DeleteProduct(intid){varresult=await_productService.DeleteAsync(id);if(!result)returnNotFound();returnNoContent();// HTTP 204 No Content}}

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

HTTP 方法	CRUD 操作	描述	幂等性	安全性
GET	Read	获取资源	是	是
POST	Create	创建新资源	否	否
PUT	Update	更新整个资源	是	否
PATCH	Update	部分更新资源	否	否
DELETE	Delete	删除资源	是	否

4.状态码使用

// 常用 HTTP 状态码returnOk(data);// 200 - 成功returnCreated(uri,data);// 201 - 创建成功returnNoContent();// 204 - 成功无内容returnBadRequest(error);// 400 - 客户端错误returnUnauthorized();// 401 - 未认证returnForbid();// 403 - 无权限returnNotFound();// 404 - 资源不存在returnConflict(error);// 409 - 冲突returnStatusCode(500,error);// 500 - 服务器错误

5.RESTful 最佳实践

// 1. 使用复数名词命名资源// 正确：/api/products、/api/users// 避免：/api/getProduct、/api/createUser// 2. 使用嵌套资源表示关系[HttpGet("api/users/{userId}/orders")]// 获取用户的订单publicIActionResultGetUserOrders(intuserId){}// 3. 使用查询参数进行过滤、分页、排序[HttpGet("api/products")]publicIActionResultGetProducts([FromQuery]stringcategory,// 过滤[FromQuery]intpage=1,// 分页[FromQuery]intpageSize=10,// 分页大小[FromQuery]stringsortBy="name"){}// 4. 使用 HATEOAS 提供超媒体链接publicclassProductDto{publicintId{get;set;}publicstringName{get;set;}publicdecimalPrice{get;set;}publicList<LinkDto>Links{get;set;}=new();}// 在控制器中添加链接productDto.Links.Add(newLinkDto(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]")]publicclassProductsController:ControllerBase{}// 或使用 Header 版本控制[ApiVersion("2.0")][Route("api/[controller]")]publicclassProductsV2Controller:ControllerBase{}