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

数据格式总结表

格式	用途	示例	适合场景
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>

总结：黄金法则

RESTful原则：
- GET：Query Params
- POST：JSON Body
- PUT/PATCH：JSON Body
- DELETE：Path Params
简单原则：
- 标识资源：Path Params
- 过滤搜索：Query Params
- 认证信息：Headers
- 复杂数据：JSON Body
- 简单表单：Form Data
- 文件上传：Multipart Form Data
一致性原则：
- 整个项目保持统一风格
- 相同功能使用相同格式
- 团队约定优先