API-标准controller接口

请求方式

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

一般情况下都使用JSON参数来使用post方式

POST-Json

java 复制代码
/**
 * 
 * 提交关键字搜索任务,并获取结果
 *
 * @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表单

java 复制代码
/**
 * 
 * 提交关键字搜索任务,并获取结果
 *
 * @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 编码

一些常用的校验

java 复制代码
@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不同场景的校验触发条件

相关推荐
overFitBrain6 分钟前
数据结构-5(二叉树)
开发语言·数据结构·python
rookiesx17 分钟前
安装本地python文件到site-packages
开发语言·前端·python
m0_6873998429 分钟前
Ubuntu22 上,用C++ gSoap 创建一个简单的webservice
开发语言·c++
屁股割了还要学29 分钟前
【C语言进阶】一篇文章教会你文件的读写
c语言·开发语言·数据结构·c++·学习·青少年编程
微露清风35 分钟前
系统性学习C语言-第二十二讲-动态内存管理
c语言·开发语言·学习
钮钴禄·爱因斯晨36 分钟前
C语言|指针的应用
c语言·开发语言
Shingmc31 小时前
【C++】二叉搜索数
开发语言·c++
一个天蝎座 白勺 程序猿1 小时前
Python(32)Python内置函数全解析:30个核心函数的语法、案例与最佳实践
android·开发语言·python
MediaTea2 小时前
Python 库手册:ssl 加密通信模块
开发语言·网络·python·网络协议·ssl
wai歪why2 小时前
C语言:深入理解指针(5)
c语言·开发语言