请求方式
- 注释要求：文档注释并说明出参和返回结果
- 请求入参：统一使用JSON进行入参【@RequestBody】
- 请求实体要求：字段都需要释标注字段说明
一般情况下都使用JSON参数来使用post方式
POST-Json
/*** * 提交关键字搜索任务，并获取结果** @module Test (对应目录)*/
@RestController
@RequestMapping("/test/xhs")
@RequiredArgsConstructor
public class TestXhsOpusTaskController {private final TestXhsOpusSearchService TestXhsOpusSearchService;/*** Test小红书作品库外搜任务提交（接口名称）* ** @param taskParams 搜索参数 * @return 任务id*/@PostMapping("/task/add")public string TaskSubmit(@Valid @RequestBody TaskParams taskParams) {return "";}
}
POST-Form表单
/*** * 提交关键字搜索任务，并获取结果** @module Test (对应目录)*/
@Validated
@RestController
@RequestMapping("/test/xhs")
@RequiredArgsConstructor
public class TestXhsOpusTaskController {private final TestXhsOpusSearchService TestXhsOpusSearchService;/*** Test小红书作品库外搜任务提交（接口名称）* ** @param taskParams 搜索参数 * @return 任务id*/@PostMapping("/task/add")public string TaskSubmit(@Valid TaskParams taskParams) {return "";}
}
AI-对比
| 对比项 | 表单请求（application/x-www-form-urlencoded） | JSON 请求（application/json） |
|---|---|---|
| 数据格式 | 类似于 key1=value1&key2=value2的字符串 | 结构化 JSON，如 { "key1": "value1" } |
| 嵌套对象 | 不支持或需手动拼接解析 | 原生支持嵌套、数组、对象 |
| 服务端解析 | Spring 自动支持（如 @RequestParam） | Spring 需配合 @RequestBody |
| 通用性 | 浏览器原生支持，适合传统表单提交 | 更通用，适合前后端分离、API 调用 |
| 安全性 | 参数暴露更明显（如在日志中） | JSON体不容易暴露参数（尤其配合HTTPS） |
| 可读性与扩展性 | 可读性差，扩展复杂 | 可读性强，扩展灵活 |
| Content-Type | application/x-www-form-urlencoded | application/json |
| 多媒体上传 | 可通过 multipart/form-data 上传文件 | 通常需额外处理，如 Base64 编码 |
一些常用的校验
@Data
public class TaskParam {/*** 平台*/@NotBlank(message = "platform不能为空")@Pattern(regexp = "dy|xhs|wb", message = "platform只能为dy|xhs|wb")private String platform;/*** 页数*/@NotNull(message = "page不能为空")@Min(value = 1, message = "page 最小为1")private int page = 1;/*** 大小*/@NotNull(message = "size不能为空")@Max(value = 200, message = "size 最大为200")private int size = 20;@Valid@NotEmpty(message = "list不能为空")private List<ManageParam> list;/*** 开始日期*/@CustomTime(format = "yyyy-MM-dd")private String startDate;
}
@Valid不同场景的校验触发条件
)
