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不同场景的校验触发条件

相关推荐
梦子要转行3 分钟前
matlab/Simulink-全套50个汽车性能建模与仿真源码模型9
开发语言·matlab·汽车
北方有星辰zz35 分钟前
数据结构:栈
java·开发语言·数据结构
我是唐青枫1 小时前
C#.NET NLog 详解
开发语言·c#·.net
Mr_Xuhhh1 小时前
网络基础(1)
c语言·开发语言·网络·c++·qt·算法
旺旺大力包1 小时前
【JS笔记】JS 和 noodjs 的常见操作(十)
开发语言·javascript·node.js·ecmascript
草履虫建模1 小时前
Postman - API 调试与开发工具 - 标准使用流程
java·测试工具·spring·json·测试用例·postman·集成学习
背影疾风2 小时前
C++之路:类基础、构造析构、拷贝构造函数
linux·开发语言·c++
Ting-yu2 小时前
Java中Stream流的使用
java·开发语言·windows
【ql君】qlexcel3 小时前
Notepad++ 复制宏、编辑宏的方法
开发语言·javascript·notepad++··宏编辑·宏复制
Zevalin爱灰灰3 小时前
MATLAB GUI界面设计 第六章——常用库中的其它组件
开发语言·ui·matlab