接口联调总卡壳？先问自己：真的搞清楚 HTTP 的 Header 和 Body 了吗？

前几天帮组里的新人排查接口问题，看着他对着 Postman 里的 400 错误抓耳挠腮 ------ 明明 JSON 格式没问题，参数也全对，怎么就是调不通？最后我指着请求头里的Content-Type问他："你这写的x-www-form-urlencoded，body 里却塞 JSON，服务器能认吗？"

那一刻突然意识到，HTTP 里的 header 和 body 这两个基础组件，看似简单，却藏着无数开发老兵都踩过的坑。今天就从 Java 开发的实战视角，扒一扒这对 "黄金搭档" 的门道。

刚入行那年，我接手过一个第三方支付对接的需求。本地测试一切正常，上线后却频繁报 403 Forbidden。查了三天日志，最后发现是生产环境的请求少了个User-Agent头 ------ 对方服务器会拦截没有客户端标识的请求。

还有一次更离谱，用HttpURLConnection发请求时，把setRequestProperty放在了connect()之后，导致自定义的X-API-Version头始终没传过去。当时还怀疑是对方接口有问题，现在想起来都觉得脸红。

这些教训让我明白：header 是 HTTP 请求的 "身份证" 和 "操作说明"，丢了或者填错，再对的 body 也白搭。

如果把 HTTP 请求比作快递，那 header 就是贴在包裹上的面单 ------ 不包含货物本身，却决定了包裹怎么送、送给谁、怎么处理。作为 Java 开发者，这几类 header 必须刻在脑子里：

Content-Type：这是 header 和 body 之间的 "翻译官"，告诉服务器 body 的数据格式。Java 开发里最常用的三种：
- application/json：JSON 数据，用 Gson/Jackson 序列化时必须对应
- multipart/form-data：文件上传专用，OkHttp 里要用MultipartBody构建
- application/x-www-form-urlencoded：表单提交，对应FormBody之前新人踩的坑，本质就是Content-Type和 body 格式 mismatch。
Authorization ：身份认证的 "通行证"。现在主流的 JWT 认证，必须用Bearer token格式：
arduino 复制代码
```
// OkHttp正确写法
.header("Authorization", "Bearer " + userToken)
```
千万别图省事把 token 塞 body 里，既不安全也不符合规范。
Accept ：告诉服务器 "我能看懂什么格式"，比如只接受 JSON 就写application/json，避免服务器返回 XML 格式导致解析报错。

2. Java 开发的坑点与避坑术

设置时机陷阱 ：用HttpURLConnection时，必须在connect()或获取流之前设置 header，否则无效：

arduino 复制代码

// 错误写法：connect后设置header
connection.connect();
connection.setRequestProperty("User-Agent", "MyApp/1.0"); 

// 正确写法：先设header再连接
connection.setRequestProperty("User-Agent", "MyApp/1.0");
connection.connect();

重复 header 问题 ：OkHttp 的header()会覆盖同名头，addHeader()会保留多个值。比如多次添加Cache-Control，要用对方法。
自定义 header 规范 ：团队内部的自定义头建议加前缀，比如X-Company-Request-Id，避免和标准头冲突。

三、body：包裹里的 "核心货物"

如果说 header 是面单，那 body 就是快递里的实际货物 ------ 承载着业务核心数据。但 Java 开发里，body 的坑一点不比 header 少。

1. 什么时候该用 body？

POST/PUT 请求的业务数据：比如创建用户的name、age等参数
复杂结构化数据：JSON 对象比拼接 URL 参数更清晰
二进制数据：文件上传、图片传输等场景

这里要纠正一个常见误区：GET 请求可以有 body，但几乎所有服务器都不处理。曾经见过有人为了传大量参数，给 GET 请求加 body，结果服务器接收不到数据，排查半天才发现问题。

2. 三种常见 body 类型的 Java 实战

（1）JSON 格式（最常用）

用 Gson 序列化对象时，要注意字段名和服务器保持一致：

ini 复制代码

// 正确示例：配合Content-Type: application/json
User user = new User("张三", 28);
String json = new Gson().toJson(user);
RequestBody body = RequestBody.create(json, MediaType.parse("application/json"));

坑点：如果服务器用下划线命名（如user_name），Java 对象要用@SerializedName注解适配，否则会出现字段缺失。

（2）表单格式

适合简单键值对，OkHttp 的FormBody是标配：

csharp 复制代码

RequestBody formBody = new FormBody.Builder()
        .add("username", "zhangsan")
        .add("password", "123456") // 实际开发要加密！
        .build();

注意：此时Content-Type会自动设为application/x-www-form-urlencoded，无需手动添加。

（3）文件上传格式

必须用multipart/form-data，结合MultipartBody：

java 复制代码

RequestBody fileBody = RequestBody.create(new File("test.pdf"), MediaType.parse("application/pdf"));
RequestBody body = new MultipartBody.Builder()
        .setType(MultipartBody.FORM)
        .addFormDataPart("file", "test.pdf", fileBody)
        .addFormDataPart("desc", "测试文件")
        .build();

这里的文件名和 Content-Type 都要准确，否则服务器可能无法解析文件。

四、联动篇：header 和 body 的默契配合

header 和 body 从来不是孤立的，两者的配合直接决定了请求的成败。分享两个 Java 开发中最关键的联动场景：

1. 格式校验联动

服务器接收请求时，会先看Content-Type，再按对应格式解析 body。比如 SpringBoot 接口：

less 复制代码

// 必须有Content-Type: application/json才能解析
@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
    // 处理逻辑
}

如果前端传了form-data格式，即使 body 是 JSON 字符串，也会报 415 Unsupported Media Type 错误。

2. 安全与性能联动

敏感数据处理 ：密码、token 等敏感信息要放在Authorization头或 body 里，绝对不能放 URL（会被日志记录）
缓存优化 ：用ETag（响应头）和If-None-Match（请求头）配合，避免重复传输相同 body 数据，这在列表查询接口里能显著提升性能。

五、八年老鸟的避坑指南

最后总结几个实战中用血换来的经验，尤其适合 Java 开发者：

统一 header 管理 ：用 OkHttp 拦截器统一添加公共 header（如X-Request-Id、User-Agent），避免重复代码：

ini 复制代码

OkHttpClient client = new OkHttpClient.Builder()
        .addInterceptor(chain -> {
            Request original = chain.request();
            Request newRequest = original.newBuilder()
                    .header("User-Agent", "MyApp/2.0")
                    .header("X-Request-Id", UUID.randomUUID().toString())
                    .build();
            return chain.proceed(newRequest);
        })
        .build();

日志打印规范：打印请求日志时，header 要脱敏（隐藏 token），body 要限制长度（避免大文件打印撑爆日志）

接口文档明确化 ：用 Swagger 时，必须标注每个接口的Content-Type和 header 要求，比如：

less 复制代码

@ApiOperation("创建用户")
@ApiImplicitParams({
    @ApiImplicitParam(name = "Authorization", value = "Bearer token", required = true, paramType = "header")
})

排查工具用好：遇到问题先抓包，用 Fiddler 或 Charles 看完整的 header 和 body，比瞎猜高效 10 倍。

六、最后：基础扎实才是硬道理

做 Java 开发越久，越觉得 HTTP 基础的重要性。很多时候线上故障不是因为复杂的框架问题，而是Content-Type填错、header 设置时机不对这种 "小问题"。

就像开头提到的新人，后来他在笔记里写了一句话："header 是路牌，body 是 cargo，路牌指错了，再值钱的 cargo 也到不了目的地。"

你在开发中踩过哪些 header 和 body 的坑？欢迎在评论区交流，让更多人少走弯路～

接口联调总卡壳？先问自己：真的搞清楚 HTTP 的 Header 和 Body 了吗？