被虐的诺艾尔绿色中文版
4.24G · 2025-11-10
前几天帮组里的新人排查接口问题，看着他对着 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格式：
// OkHttp正确写法
.header("Authorization", "Bearer " + userToken)
千万别图省事把 token 塞 body 里，既不安全也不符合规范。
Accept：告诉服务器 “我能看懂什么格式”，比如只接受 JSON 就写application/json，避免服务器返回 XML 格式导致解析报错。
设置时机陷阱：用HttpURLConnection时，必须在connect()或获取流之前设置 header，否则无效：
// 错误写法：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，避免和标准头冲突。
如果说 header 是面单，那 body 就是快递里的实际货物 —— 承载着业务核心数据。但 Java 开发里，body 的坑一点不比 header 少。
name、age等参数这里要纠正一个常见误区：GET 请求可以有 body，但几乎所有服务器都不处理。曾经见过有人为了传大量参数，给 GET 请求加 body，结果服务器接收不到数据，排查半天才发现问题。
用 Gson 序列化对象时，要注意字段名和服务器保持一致：
// 正确示例：配合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注解适配，否则会出现字段缺失。
适合简单键值对，OkHttp 的FormBody是标配：
RequestBody formBody = new FormBody.Builder()
.add("username", "zhangsan")
.add("password", "123456") // 实际开发要加密！
.build();
注意：此时Content-Type会自动设为application/x-www-form-urlencoded，无需手动添加。
必须用multipart/form-data，结合MultipartBody：
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 从来不是孤立的，两者的配合直接决定了请求的成败。分享两个 Java 开发中最关键的联动场景：
服务器接收请求时，会先看Content-Type，再按对应格式解析 body。比如 SpringBoot 接口：
// 必须有Content-Type: application/json才能解析
@PostMapping("/users")
public ResponseEntity<User> createUser(@RequestBody User user) {
// 处理逻辑
}
如果前端传了form-data格式，即使 body 是 JSON 字符串，也会报 415 Unsupported Media Type 错误。
Authorization头或 body 里，绝对不能放 URL（会被日志记录）ETag（响应头）和If-None-Match（请求头）配合，避免重复传输相同 body 数据，这在列表查询接口里能显著提升性能。最后总结几个实战中用血换来的经验，尤其适合 Java 开发者：
统一 header 管理：用 OkHttp 拦截器统一添加公共 header（如X-Request-Id、User-Agent），避免重复代码：
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 要求，比如：
@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 的坑？欢迎在评论区交流，让更多人少走弯路～
4.24G · 2025-11-10
23G · 2025-11-10
1.28G · 2025-11-10
