469 lines
13 KiB
Plaintext
469 lines
13 KiB
Plaintext
# API 设计规范
|
|
|
|
## RESTful API 设计原则
|
|
|
|
### URL 设计规范
|
|
```
|
|
/{应用类型}-api/{模块}/{业务对象}/{操作}
|
|
|
|
示例：
|
|
/admin-api/system/user/create # 管理后台创建用户
|
|
/admin-api/system/user/page # 管理后台用户分页
|
|
/app-api/member/user/profile # 用户端获取个人信息
|
|
```
|
|
|
|
### HTTP 方法使用
|
|
```http
|
|
GET /admin-api/system/user/get # 获取单个资源
|
|
GET /admin-api/system/user/page # 获取资源列表（分页）
|
|
GET /admin-api/system/user/list # 获取资源列表（不分页）
|
|
POST /admin-api/system/user/create # 创建资源
|
|
PUT /admin-api/system/user/update # 更新资源
|
|
DELETE /admin-api/system/user/delete # 删除资源
|
|
```
|
|
|
|
### 应用类型前缀
|
|
- **admin-api**: 管理后台接口
|
|
- **app-api**: 用户端 APP 接口
|
|
- **mp-api**: 微信小程序接口
|
|
|
|
## 统一响应格式
|
|
|
|
### 成功响应
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"data": {
|
|
"id": 1,
|
|
"username": "admin",
|
|
"nickname": "管理员"
|
|
},
|
|
"msg": ""
|
|
}
|
|
```
|
|
|
|
### 错误响应
|
|
```json
|
|
{
|
|
"code": 1002001001,
|
|
"data": null,
|
|
"msg": "用户不存在"
|
|
}
|
|
```
|
|
|
|
### 分页响应
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"data": {
|
|
"list": [
|
|
{
|
|
"id": 1,
|
|
"username": "admin"
|
|
}
|
|
],
|
|
"total": 100
|
|
},
|
|
"msg": ""
|
|
}
|
|
```
|
|
|
|
## Controller 层实现规范
|
|
|
|
### 标准 Controller 结构
|
|
```java
|
|
@RestController
|
|
@RequestMapping("/admin-api/system/user")
|
|
@Api(tags = "管理后台 - 用户管理")
|
|
@Validated
|
|
public class UserController {
|
|
|
|
@Resource
|
|
private UserService userService;
|
|
|
|
@PostMapping("/create")
|
|
@ApiOperation("创建用户")
|
|
@PreAuthorize("@ss.hasPermission('system:user:create')")
|
|
@OperateLog(type = CREATE)
|
|
public CommonResult<Long> createUser(@Valid @RequestBody UserCreateReqVO reqVO) {
|
|
return success(userService.createUser(reqVO));
|
|
}
|
|
|
|
@PutMapping("/update")
|
|
@ApiOperation("修改用户")
|
|
@PreAuthorize("@ss.hasPermission('system:user:update')")
|
|
@OperateLog(type = UPDATE)
|
|
public CommonResult<Boolean> updateUser(@Valid @RequestBody UserUpdateReqVO reqVO) {
|
|
userService.updateUser(reqVO);
|
|
return success(true);
|
|
}
|
|
|
|
@DeleteMapping("/delete")
|
|
@ApiOperation("删除用户")
|
|
@PreAuthorize("@ss.hasPermission('system:user:delete')")
|
|
@OperateLog(type = DELETE)
|
|
public CommonResult<Boolean> deleteUser(@RequestParam("id") Long id) {
|
|
userService.deleteUser(id);
|
|
return success(true);
|
|
}
|
|
|
|
@GetMapping("/get")
|
|
@ApiOperation("获得用户")
|
|
@PreAuthorize("@ss.hasPermission('system:user:query')")
|
|
public CommonResult<UserRespVO> getUser(@RequestParam("id") Long id) {
|
|
UserDO user = userService.getUser(id);
|
|
return success(UserConvert.INSTANCE.convert(user));
|
|
}
|
|
|
|
@GetMapping("/page")
|
|
@ApiOperation("获得用户分页")
|
|
@PreAuthorize("@ss.hasPermission('system:user:query')")
|
|
public CommonResult<PageResult<UserRespVO>> getUserPage(@Valid UserPageReqVO reqVO) {
|
|
PageResult<UserDO> pageResult = userService.getUserPage(reqVO);
|
|
return success(UserConvert.INSTANCE.convertPage(pageResult));
|
|
}
|
|
|
|
@GetMapping("/list")
|
|
@ApiOperation("获得用户列表")
|
|
@PreAuthorize("@ss.hasPermission('system:user:query')")
|
|
public CommonResult<List<UserRespVO>> getUserList(@Valid UserListReqVO reqVO) {
|
|
List<UserDO> list = userService.getUserList(reqVO);
|
|
return success(UserConvert.INSTANCE.convertList(list));
|
|
}
|
|
}
|
|
```
|
|
|
|
### 必备注解使用
|
|
```java
|
|
// 类级别注解
|
|
@RestController // 声明为REST控制器
|
|
@RequestMapping("/admin-api/system/user") // 请求路径映射
|
|
@Api(tags = "管理后台 - 用户管理") // API文档分组
|
|
@Validated // 启用参数校验
|
|
|
|
// 方法级别注解
|
|
@PostMapping("/create") // HTTP方法映射
|
|
@ApiOperation("创建用户") // API文档说明
|
|
@PreAuthorize("@ss.hasPermission('system:user:create')") // 权限控制
|
|
@OperateLog(type = CREATE) // 操作日志
|
|
```
|
|
|
|
## 请求参数规范
|
|
|
|
### 创建请求 VO
|
|
```java
|
|
@Data
|
|
@ApiModel("用户创建 Request VO")
|
|
public class UserCreateReqVO {
|
|
|
|
@ApiModelProperty(value = "用户账号", required = true, example = "admin")
|
|
@NotBlank(message = "用户账号不能为空")
|
|
@Size(max = 30, message = "用户账号长度不能超过30个字符")
|
|
private String username;
|
|
|
|
@ApiModelProperty(value = "用户昵称", required = true, example = "管理员")
|
|
@NotBlank(message = "用户昵称不能为空")
|
|
@Size(max = 30, message = "用户昵称长度不能超过30个字符")
|
|
private String nickname;
|
|
|
|
@ApiModelProperty(value = "用户邮箱", example = "admin@example.com")
|
|
@Email(message = "邮箱格式不正确")
|
|
@Size(max = 50, message = "邮箱长度不能超过50个字符")
|
|
private String email;
|
|
|
|
@ApiModelProperty(value = "手机号码", example = "15601691300")
|
|
@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号码格式不正确")
|
|
private String mobile;
|
|
|
|
@ApiModelProperty(value = "用户性别", example = "1")
|
|
@InEnum(CommonStatusEnum.class, message = "修改状态必须是 {value}")
|
|
private Integer sex;
|
|
|
|
@ApiModelProperty(value = "部门ID", example = "1")
|
|
@NotNull(message = "部门不能为空")
|
|
private Long deptId;
|
|
|
|
@ApiModelProperty(value = "岗位编号数组", example = "1")
|
|
private Set<Long> postIds;
|
|
|
|
@ApiModelProperty(value = "用户角色编号数组", example = "1")
|
|
private Set<Long> roleIds;
|
|
}
|
|
```
|
|
|
|
### 更新请求 VO
|
|
```java
|
|
@Data
|
|
@ApiModel("用户更新 Request VO")
|
|
public class UserUpdateReqVO {
|
|
|
|
@ApiModelProperty(value = "用户编号", required = true, example = "1")
|
|
@NotNull(message = "用户编号不能为空")
|
|
private Long id;
|
|
|
|
// 其他字段与创建请求相同...
|
|
}
|
|
```
|
|
|
|
### 分页查询 VO
|
|
```java
|
|
@Data
|
|
@EqualsAndHashCode(callSuper = true)
|
|
@ApiModel("用户分页 Request VO")
|
|
public class UserPageReqVO extends PageParam {
|
|
|
|
@ApiModelProperty(value = "用户账号", example = "admin")
|
|
private String username;
|
|
|
|
@ApiModelProperty(value = "手机号码", example = "15601691300")
|
|
private String mobile;
|
|
|
|
@ApiModelProperty(value = "展示状态", example = "1")
|
|
@InEnum(CommonStatusEnum.class, message = "状态必须是 {value}")
|
|
private Integer status;
|
|
|
|
@ApiModelProperty(value = "创建时间", example = "[2022-07-01 00:00:00,2022-07-01 23:59:59]")
|
|
@DateTimeFormat(pattern = FORMAT_YEAR_MONTH_DAY_HOUR_MINUTE_SECOND)
|
|
private LocalDateTime[] createTime;
|
|
|
|
@ApiModelProperty(value = "部门编号", example = "1")
|
|
private Long deptId;
|
|
}
|
|
```
|
|
|
|
## 响应参数规范
|
|
|
|
### 响应 VO
|
|
```java
|
|
@Data
|
|
@ApiModel("用户信息 Response VO")
|
|
public class UserRespVO {
|
|
|
|
@ApiModelProperty(value = "用户编号", example = "1")
|
|
private Long id;
|
|
|
|
@ApiModelProperty(value = "用户账号", example = "admin")
|
|
private String username;
|
|
|
|
@ApiModelProperty(value = "用户昵称", example = "管理员")
|
|
private String nickname;
|
|
|
|
@ApiModelProperty(value = "用户邮箱", example = "admin@example.com")
|
|
private String email;
|
|
|
|
@ApiModelProperty(value = "手机号码", example = "15601691300")
|
|
private String mobile;
|
|
|
|
@ApiModelProperty(value = "用户性别", example = "1")
|
|
private Integer sex;
|
|
|
|
@ApiModelProperty(value = "用户头像", example = "https://www.example.com/avatar.jpg")
|
|
private String avatar;
|
|
|
|
@ApiModelProperty(value = "帐号状态", example = "1")
|
|
private Integer status;
|
|
|
|
@ApiModelProperty(value = "最后登录IP", example = "192.168.1.1")
|
|
private String loginIp;
|
|
|
|
@ApiModelProperty(value = "最后登录时间", example = "2022-01-01 00:00:00")
|
|
private LocalDateTime loginDate;
|
|
|
|
@ApiModelProperty(value = "创建时间", example = "2022-01-01 00:00:00")
|
|
private LocalDateTime createTime;
|
|
|
|
/**
|
|
* 所属角色
|
|
*/
|
|
private Set<Long> roleIds;
|
|
|
|
/**
|
|
* 所属岗位
|
|
*/
|
|
private Set<Long> postIds;
|
|
|
|
/**
|
|
* 所属部门
|
|
*/
|
|
@ApiModelProperty(value = "部门编号", example = "1")
|
|
private Long deptId;
|
|
}
|
|
```
|
|
|
|
## 参数校验规范
|
|
|
|
### 常用校验注解
|
|
```java
|
|
// 非空校验
|
|
@NotNull(message = "ID不能为空")
|
|
@NotBlank(message = "用户名不能为空")
|
|
@NotEmpty(message = "角色列表不能为空")
|
|
|
|
// 长度校验
|
|
@Size(min = 2, max = 30, message = "用户名长度必须在2-30字符之间")
|
|
@Length(max = 50, message = "邮箱长度不能超过50个字符")
|
|
|
|
// 格式校验
|
|
@Email(message = "邮箱格式不正确")
|
|
@Pattern(regexp = "^1[3-9]\\d{9}$", message = "手机号码格式不正确")
|
|
|
|
// 数值校验
|
|
@Min(value = 0, message = "年龄不能小于0")
|
|
@Max(value = 150, message = "年龄不能大于150")
|
|
@Range(min = 1, max = 100, message = "百分比必须在1-100之间")
|
|
|
|
// 自定义校验
|
|
@InEnum(CommonStatusEnum.class, message = "状态必须是 {value}")
|
|
```
|
|
|
|
### 分组校验
|
|
```java
|
|
// 定义校验分组
|
|
public interface AddGroup {}
|
|
public interface UpdateGroup {}
|
|
|
|
// 在字段上使用分组
|
|
@NotNull(groups = UpdateGroup.class, message = "ID不能为空")
|
|
private Long id;
|
|
|
|
@NotBlank(groups = {AddGroup.class, UpdateGroup.class}, message = "用户名不能为空")
|
|
private String username;
|
|
|
|
// 在Controller中指定分组
|
|
@PostMapping("/create")
|
|
public CommonResult<Long> createUser(@Validated(AddGroup.class) @RequestBody UserSaveReqVO reqVO) {
|
|
return success(userService.createUser(reqVO));
|
|
}
|
|
```
|
|
|
|
## 异常处理规范
|
|
|
|
### 全局异常处理
|
|
```java
|
|
@RestControllerAdvice
|
|
public class GlobalExceptionHandler {
|
|
|
|
/**
|
|
* 处理业务异常
|
|
*/
|
|
@ExceptionHandler(ServiceException.class)
|
|
public CommonResult<?> serviceExceptionHandler(ServiceException ex) {
|
|
log.info("[serviceExceptionHandler]", ex);
|
|
return CommonResult.error(ex.getCode(), ex.getMessage());
|
|
}
|
|
|
|
/**
|
|
* 处理参数校验异常
|
|
*/
|
|
@ExceptionHandler(MethodArgumentNotValidException.class)
|
|
public CommonResult<?> methodArgumentNotValidExceptionHandler(MethodArgumentNotValidException ex) {
|
|
FieldError fieldError = ex.getBindingResult().getFieldError();
|
|
assert fieldError != null;
|
|
return CommonResult.error(BAD_REQUEST.getCode(), String.format("请求参数不正确:%s", fieldError.getDefaultMessage()));
|
|
}
|
|
}
|
|
```
|
|
|
|
### 业务异常抛出
|
|
```java
|
|
// 在Service中抛出业务异常
|
|
public void validateUserExists(Long id) {
|
|
if (userMapper.selectById(id) == null) {
|
|
throw exception(USER_NOT_EXISTS);
|
|
}
|
|
}
|
|
|
|
// 错误码定义
|
|
public interface ErrorCodeConstants {
|
|
ErrorCode USER_NOT_EXISTS = new ErrorCode(1002001001, "用户不存在");
|
|
ErrorCode USER_USERNAME_EXISTS = new ErrorCode(1002001002, "用户账号已经存在");
|
|
}
|
|
```
|
|
|
|
## 接口文档规范
|
|
|
|
### Swagger 注解使用
|
|
```java
|
|
@Api(tags = "管理后台 - 用户管理") // 控制器分组
|
|
@ApiOperation("创建用户") // 接口说明
|
|
@ApiParam(value = "用户ID", required = true) // 参数说明
|
|
|
|
@ApiModel("用户信息") // 模型说明
|
|
@ApiModelProperty(value = "用户编号", example = "1") // 字段说明
|
|
```
|
|
|
|
### 接口文档示例
|
|
```yaml
|
|
# 生成的 OpenAPI 文档格式
|
|
paths:
|
|
/admin-api/system/user/create:
|
|
post:
|
|
tags:
|
|
- 管理后台 - 用户管理
|
|
summary: 创建用户
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserCreateReqVO'
|
|
responses:
|
|
'200':
|
|
description: 成功
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CommonResultLong'
|
|
```
|
|
|
|
## 版本管理
|
|
|
|
### API 版本控制
|
|
```java
|
|
// 使用路径版本控制
|
|
@RequestMapping("/admin-api/v1/system/user")
|
|
|
|
// 使用请求头版本控制
|
|
@RequestMapping(value = "/admin-api/system/user", headers = "version=1.0")
|
|
|
|
// 使用参数版本控制
|
|
@RequestMapping(value = "/admin-api/system/user", params = "version=1.0")
|
|
```
|
|
|
|
### 向后兼容
|
|
- 新增字段设为可选
|
|
- 保持现有字段不变
|
|
- 废弃字段标记 @Deprecated
|
|
- 提供迁移指南
|
|
|
|
## 性能优化
|
|
|
|
### 批量操作
|
|
```java
|
|
@PostMapping("/batch-delete")
|
|
@ApiOperation("批量删除用户")
|
|
public CommonResult<Boolean> deleteUsers(@RequestBody Set<Long> ids) {
|
|
userService.deleteUsers(ids);
|
|
return success(true);
|
|
}
|
|
```
|
|
|
|
### 异步处理
|
|
```java
|
|
@PostMapping("/export")
|
|
@ApiOperation("导出用户数据")
|
|
public CommonResult<String> exportUsers(@Valid UserExportReqVO reqVO) {
|
|
// 异步处理导出任务
|
|
String taskId = userService.exportUsersAsync(reqVO);
|
|
return success(taskId);
|
|
}
|
|
```
|
|
|
|
### 缓存策略
|
|
```java
|
|
@GetMapping("/get")
|
|
@Cacheable(value = "user", key = "#id")
|
|
public CommonResult<UserRespVO> getUser(@RequestParam("id") Long id) {
|
|
UserDO user = userService.getUser(id);
|
|
return success(UserConvert.INSTANCE.convert(user));
|
|
}
|
|
``` |