nArchitecture WebAPI开发教程：Controllers层实现RESTful接口

nArchitecture WebAPI开发教程：Controllers层实现RESTful接口

【免费下载链接】nArchitectureInspired by Clean Architecture, nArchitecture is a monolith project which uses advanced techniques.项目地址: https://gitcode.com/gh_mirrors/na/nArchitecture

nArchitecture是一个受Clean Architecture启发的单体项目，它采用先进技术构建。本教程将详细介绍如何在nArchitecture项目的Controllers层实现RESTful接口，帮助开发者快速掌握WebAPI的开发方法。

1. Controllers层基础架构

在nArchitecture项目中，Controllers层位于src/starterProject/WebAPI/Controllers目录下，所有控制器都继承自BaseController。BaseController是整个控制器层的基础，它提供了一些通用的功能和属性。

BaseController的核心代码如下：

public class BaseController : ControllerBase { protected IMediator Mediator => _mediator ??= HttpContext.RequestServices.GetService<IMediator>() ?? throw new InvalidOperationException("IMediator cannot be retrieved from request services."); private IMediator? _mediator; protected string getIpAddress() { // 获取IP地址的实现 } protected Guid getUserIdFromRequest() { // 从请求中获取用户ID的实现 } }

从上述代码可以看出，BaseController主要提供了以下功能：

• 通过依赖注入获取IMediator实例，用于实现命令和查询的发送
• 提供获取客户端IP地址的方法
• 提供从请求中获取用户ID的方法

2. RESTful接口设计规范

nArchitecture项目中的Controllers层严格遵循RESTful接口设计规范，主要体现在以下几个方面：

2.1 HTTP方法的使用

项目中使用了标准的HTTP方法来表示不同的操作：

• GET：用于获取资源
• POST：用于创建资源
• PUT：用于更新资源
• DELETE：用于删除资源

例如，在UsersController中，我们可以看到以下HTTP方法的使用：

[HttpGet("{Id}")] [HttpGet("GetFromAuth")] [HttpGet] [HttpPost] [HttpPut] [HttpPut("FromAuth")] [HttpDelete]

2.2 URL路径设计

URL路径的设计遵循资源导向的原则，通常使用名词复数形式来表示资源集合，使用ID来表示单个资源。例如：

• /api/users：表示用户资源集合
• /api/users/{Id}：表示特定ID的用户资源

2.3 状态码使用

控制器方法应返回适当的HTTP状态码，以表示请求的处理结果：

• 200 OK：请求成功
• 201 Created：资源创建成功
• 400 Bad Request：请求参数错误
• 401 Unauthorized：未授权
• 404 Not Found：资源不存在
• 500 Internal Server Error：服务器内部错误

3. 控制器实现示例

下面以UsersController为例，详细介绍如何实现RESTful接口。

3.1 控制器定义

首先，创建一个继承自BaseController的控制器类：

public class UsersController : BaseController { // 控制器方法将在这里实现 }

3.2 获取资源

获取资源通常使用GET方法，可以获取资源集合或单个资源。

获取用户列表：

[HttpGet] public async Task<IActionResult> GetList([FromQuery] GetListUserQuery getListUserQuery) { GetListResponse<GetListUserListItemDto> response = await Mediator.Send(getListUserQuery); return Ok(response); }

获取单个用户：

[HttpGet("{Id}")] public async Task<IActionResult> GetById([FromRoute] Guid Id) { GetByIdUserQuery getByIdUserQuery = new() { Id = Id }; GetByIdUserResponse response = await Mediator.Send(getByIdUserQuery); return Ok(response); }

3.3 创建资源

创建资源使用POST方法：

[HttpPost] public async Task<IActionResult> Add([FromBody] CreateUserCommand createUserCommand) { CreatedUserResponse response = await Mediator.Send(createUserCommand); return Created(uri: "", response); }

3.4 更新资源

更新资源使用PUT方法：

[HttpPut] public async Task<IActionResult> Update([FromBody] UpdateUserCommand updateUserCommand) { UpdatedUserResponse response = await Mediator.Send(updateUserCommand); return Ok(response); }

3.5 删除资源

删除资源使用DELETE方法：

[HttpDelete] public async Task<IActionResult> Delete([FromBody] DeleteUserCommand deleteUserCommand) { DeletedUserResponse response = await Mediator.Send(deleteUserCommand); return Ok(response); }

4. 其他控制器实现

除了UsersController，nArchitecture项目中还有其他几个主要的控制器：

4.1 AuthController

AuthController负责处理身份验证相关的接口，如登录、注册、刷新令牌等：

[HttpPost("Login")] [HttpPost("Register")] [HttpGet("RefreshToken")] [HttpPut("RevokeToken")] [HttpGet("EnableEmailAuthenticator")] [HttpGet("EnableOtpAuthenticator")] [HttpGet("VerifyEmailAuthenticator")] [HttpPost("VerifyOtpAuthenticator")]

4.2 OperationClaimsController

OperationClaimsController用于管理操作权限：

[HttpGet("{Id}")] [HttpGet] [HttpPost] [HttpPut] [HttpDelete]

4.3 UserOperationClaimsController

UserOperationClaimsController用于管理用户与操作权限之间的关系：

[HttpGet("{Id}")] [HttpGet] [HttpPost] [HttpPut] [HttpDelete]

5. 总结

通过本教程，我们了解了nArchitecture项目中Controllers层的实现方式。主要关键点包括：

• 所有控制器都继承自BaseController，它提供了通用的功能
• 严格遵循RESTful接口设计规范，包括HTTP方法、URL路径和状态码的使用
• 使用MediatR来实现命令和查询的发送，实现了控制器与业务逻辑的解耦

如果你想深入学习nArchitecture项目的WebAPI开发，可以查看项目中的源代码，特别是src/starterProject/WebAPI/Controllers目录下的各个控制器文件。通过实际的代码示例，你可以更好地理解和掌握RESTful接口的实现方法。

要开始使用nArchitecture项目，你可以通过以下命令克隆仓库：

git clone https://gitcode.com/gh_mirrors/na/nArchitecture

希望本教程对你有所帮助，祝你在nArchitecture项目的开发中取得成功！ 🚀

【免费下载链接】nArchitectureInspired by Clean Architecture, nArchitecture is a monolith project which uses advanced techniques.项目地址: https://gitcode.com/gh_mirrors/na/nArchitecture