API-标准controller接口

请求方式

1. 注释要求：文档注释并说明出参和返回结果
2. 请求入参：统一使用JSON进行入参【@RequestBody】
3. 请求实体要求：字段都需要释标注字段说明

一般情况下都使用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不同场景的校验触发条件