.net core webapi restful 风格 方法命名

在 .NET Core WebAPI 中遵循 ‌RESTful 风格‌时，方法命名需要与 ‌HTTP 方法‌和 ‌资源操作语义‌强关联。以下是命名规范及示例：

一、核心命名原则

语义清晰‌
方法名应直接反映操作的目标资源（如 Users、Products）和动作类型（如 Get、Create）。

HTTP 动词映射‌
使用 [HttpGet]、[HttpPost] 等属性显式声明 HTTP 方法，方法名需与 HTTP 动词语义一致。

避免冗余‌
控制器类名已包含资源名（如 UsersController），方法名无需重复资源（例如用 Get() 而非 GetUsers()）。

二、具体命名规范
1. ‌获取资源‌（HTTP GET）

获取集合‌：GetAll 或 Get

csharp
Copy Code
[HttpGet]
public ActionResult<IEnumerable<User>> Get()
{
    // 返回所有用户
}


获取单个资源‌：GetById 或 Get

csharp
Copy Code
[HttpGet("{id}")]
public ActionResult<User> Get(int id)
{
    // 返回指定ID的用户
}


条件筛选/分页‌：GetBy[条件]

csharp
Copy Code
[HttpGet("filter")]
public ActionResult<IEnumerable<User>> GetByAge([FromQuery] int minAge)
{
    // 按年龄筛选用户
}

[HttpGet("paged")]
public ActionResult<PagedList<User>> GetWithPaging([FromQuery] int page, int pageSize)
{
    // 分页查询用户
}

2. ‌创建资源‌（HTTP POST）
标准命名‌：Create
csharp
Copy Code
[HttpPost]
public ActionResult<User> Create([FromBody] User user)
{
    // 创建新用户
}

3. ‌更新资源‌（HTTP PUT/PATCH）

全量更新‌（PUT）：Update

csharp
Copy Code
[HttpPut("{id}")]
public IActionResult Update(int id, [FromBody] User user)
{
    // 替换整个用户数据
}


部分更新‌（PATCH）：Patch

csharp
Copy Code
[HttpPatch("{id}/email")]
public IActionResult PatchEmail(int id, [FromBody] string newEmail)
{
    // 仅更新用户邮箱
}

4. ‌删除资源‌（HTTP DELETE）

标准命名‌：Delete

csharp
Copy Code
[HttpDelete("{id}")]
public IActionResult Delete(int id)
{
    // 删除指定ID的用户
}


批量删除‌：DeleteMultiple

csharp
Copy Code
[HttpDelete]
public IActionResult DeleteMultiple([FromBody] List<int> ids)
{
    // 批量删除用户
}

三、特殊场景命名
1. ‌子资源操作‌

使用 / 分隔父资源和子资源，方法名体现层级关系：

csharp
Copy Code
[HttpGet("{userId}/orders")]
public ActionResult<IEnumerable<Order>> GetUserOrders(int userId)
{
    // 获取用户的所有订单
}

2. ‌异步方法‌

推荐添加 Async 后缀（符合 .NET 异步规范）：

csharp
Copy Code
[HttpGet]
public async Task<ActionResult<IEnumerable<User>>> GetAllAsync()
{
    // 异步获取所有用户
}

四、最佳实践

语义一致性‌
同一资源的操作应保持命名风格统一（例如 Get/Create/Update/Delete）。

避免动词冗余‌
错误示例 ❌：

csharp
Copy Code
[HttpPost]
public IActionResult PostCreateUser([FromBody] User user)  // 冗余的 "Post" 前缀


自定义路由覆盖‌
若需自定义路由，保持方法名与操作语义一致：

csharp
Copy Code
[HttpPost("validate")]
public IActionResult Validate([FromBody] User user)
{
    // 验证用户数据
}


团队规范优先‌
遵循团队内部约定的命名规则（如统一用 Get 或 GetAll）。

通过以上规范，可确保 API 方法命名清晰、符合 RESTful 设计原则，并提升代码可读性和维护性。