前端传输的数据格式的选择

数据格式总结表

格式	用途	示例	适合场景
Path Params​	URL路径中的参数	/users/123	资源标识、RESTful资源
Query Params​	URL问号后的参数	?page=1&size=10	过滤、分页、搜索
Headers​	请求头信息	Authorization: token	认证、元数据、控制信息
JSON Body​	JSON格式请求体	{"name":"John"}	CRUD操作、复杂对象
Form Data​	表单格式	name=John&age=25	简单表单、文件上传
x-www-form-urlencoded​	URL编码表单	同Form Data	传统表单提交
Multipart/form-data​	多部分表单	文件上传	文件上传

详细解释和选择指南

1. Path Params（路径参数）

使用场景：标识具体资源

请求路径后的大括号

// RESTful风格
@GetMapping("/users/{id}")        // 获取特定用户
@GetMapping("/words/{id}")        // 获取特定单词
@DeleteMapping("/words/{id}")     // 删除特定单词

最佳实践：

• 用于资源的唯一标识

• 通常是ID、用户名等

• 保持URL简洁

示例：

GET    /api/words/123          # 获取ID=123的单词
DELETE /api/words/123          # 删除ID=123的单词
GET    /api/users/john/words   # 获取john用户的单词

2. Query Params（查询参数）

使用场景：过滤、搜索、分页

@RequestParam注解

// 查询参数
@GetMapping("/words")
public Result searchWords(
    @RequestParam(required = false) String keyword,  // 搜索词
    @RequestParam(required = false) String pos,      // 词性过滤
    @RequestParam(defaultValue = "1") int page,      // 页码
    @RequestParam(defaultValue = "10") int size      // 每页大小
) {
    // 业务逻辑
}

最佳实践：

• 用于可选参数

• 用于过滤、排序、分页

• 参数有默认值

示例：

GET /api/words?keyword=hello&pos=n.&page=1&size=10
GET /api/words?sort=createTime&order=desc
GET /api/search?q=hello%20world

3. Headers（请求头）

使用场景：认证、元数据、控制信息

+注解@RequestHeader

// 从Header获取Token
@PostMapping("/secure-data")
public Result getSecureData(
    @RequestHeader("Authorization") String token,
    @RequestHeader(value = "X-Client-Version", required = false) String clientVersion
) {
    // 验证token
    // 根据clientVersion返回不同格式
}

最佳实践：

• 认证信息：Authorization, Token

• 客户端信息：User-Agent, X-Client-Version

• 内容协商：Accept, Content-Type

• 缓存控制：If-Modified-Since

常用Headers：

Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json
X-API-Key: your-api-key
X-Request-ID: unique-id

4. JSON Body（JSON请求体）

使用场景：创建、更新复杂对象

// 创建单词
@PostMapping("/words")
public Result addWord(@RequestBody @Valid WordDTO wordDTO) {
    // wordDTO包含所有字段
}

最佳实践：

• 用于创建资源（POST）

• 用于更新资源（PUT/PATCH）

• 对象结构复杂

• 需要验证的数据

示例：

// POST /api/words
{
  "word": "hello",
  "meaning": "你好",
  "phonetic": "/həˈləʊ/",
  "pos": "int.",
  "examples": ["Hello world!", "Say hello to her."]
}

5. Form Data / x-www-form-urlencoded

使用场景：简单表单、文件上传

// 表单提交
@PostMapping(value = "/login", consumes = MediaType.APPLICATION_FORM_URLENCODED_VALUE)
public Result login(
    @RequestParam String username,
    @RequestParam String password
) {
    // 登录逻辑
}

最佳实践：

• 传统HTML表单提交

• 文件上传（用multipart/form-data）

• 简单的键值对

• 不需要嵌套结构

示例：

<!-- HTML表单 -->
<form action="/api/login" method="post">
  <input name="username" value="admin">
  <input name="password" value="123456">
  <input type="file" name="avatar">
  <button>提交</button>
</form>

总结：黄金法则

1. RESTful原则：

   • GET：Query Params

   • POST：JSON Body

   • PUT/PATCH：JSON Body

   • DELETE：Path Params

2. 简单原则：

   • 标识资源：Path Params

   • 过滤搜索：Query Params

   • 认证信息：Headers

   • 复杂数据：JSON Body

   • 简单表单：Form Data

   • 文件上传：Multipart Form Data

3. 一致性原则：

   • 整个项目保持统一风格

   • 相同功能使用相同格式

   • 团队约定优先