Java技术栈 —— 基本规范

一、接口文档生成工具
二、接口设计
- 2.1 开发顺序
- 2.2 接口规范
三、数据类封装

一、接口文档生成工具

有很多jar包都支持swagger的接口文档，这样方便了接口测试，不需要用apifox自己写接口，直接调用文档里的swagger接口文档即可，但是市面上支持swagger的jar包众多，如何选，哪个好，这是需要比较才知道的。推荐Springdoc。

参考文章或视频链接
[1] Springfox、Swagger 和 Springdoc
[2] 从 SpringFox 迁移到 SpringDoc - 知乎
[3] 前后端分离模式中，swagger VS springdoc，你会用哪个？ - 知乎

二、接口设计

2.1 开发顺序

顺序：增（Create）→ 查（Read）→ 改（Update）→ 删（Delete）
对应 HTTP 方法：POST → GET → PUT/PATCH → DELETE
逻辑合理性
资源创建优先：用户通常需要先创建资源（如注册用户、新增文章），才能进行后续操作。
生命周期连贯：符合资源从“诞生”到“消亡”的自然流程：创建 → 查看 → 修改 → 删除。
开发文档友好：API 文档中按此顺序排列，便于开发者理解接口的完整流程。

# 示例（用户接口）
POST /users → 新增用户
GET /users/{id} → 查询用户
PUT /users/{id} → 修改用户
DELETE /users/{id} → 删除用户

2.2 接口规范

有两个接口请求，一个是GET请求，一个是POST请求，那么GET请求不支持请求体，而POST请求支持请求体。
Query Parameters，查询参数
Path Parameters，路径参数
Body Parameters，请求体参数，其中又分为Form Data、JSON Payload、XML 参数

参数类型位置术语典型场景
查询参数 URL 的 ? 后 Query Parameters 过滤、分页、排序
路径参数 URL 路径中 Path Parameters 标识唯一资源（如 /users/{id}）
请求体参数 HTTP Body Body Parameters 提交表单、JSON、文件等
表单数据 Body（表单格式） Form Data 传统表单提交
JSON 数据 Body（JSON格式） JSON Payload/Parameters 现代 API 数据交互

    @GetMapping("/list")public TableDataInfo<YourVo> list(YourBo bo, PageQuery pageQuery) {log.info("列表查询");return yourService.queryList(bo, pageQuery);}