数码常识网
霓虹主题四 · 更硬核的阅读氛围

REST API 请求头规范:开发中不可忽视的细节

发布时间:2025-12-23 21:31:14 阅读:163 次

做前后端对接时,很多人只关注接口地址和参数,却忽略了请求头(Request Headers)的重要性。其实,一个规范的 REST API 请求头不仅能提升通信效率,还能避免不少莫名其妙的错误。

常见的请求头字段

在调用 REST API 时,以下几个请求头字段几乎天天见:

  • Content-Type:告诉服务器你发的数据是什么格式。比如发 JSON 数据,就得写 application/json;如果是表单提交,就是 application/x-www-form-urlencoded
  • Authorization:用于身份验证。常见的是 Bearer Token,比如登录后拿到的 JWT 就放在这里。
  • Accept:声明客户端希望收到什么类型的数据。比如只想接收 JSON,就可以设为 application/json
  • User-Agent:标识客户端类型,有些 API 会根据这个判断是否放行请求。

Content-Type 到底怎么写?

很多人在 POST 提交数据时,明明传了 JSON,却忘了改 Content-Type,结果后端收不到数据。正确写法如下:

POST /api/users HTTP/1.1\nHost: example.com\nContent-Type: application/json\nAuthorization: Bearer eyJhbGciOiJIUzI1NiIs...\n\n{\n  "name": "zhangsan",\n  "age": 25\n}

如果这里 Content-Type 写成 text/plain 或者干脆不写,后端框架可能不会解析 body,导致参数为空。

跨域请求中的请求头

前端在浏览器里调接口,一旦涉及跨域,浏览器会先发一个 OPTIONS 预检请求。这时候,服务器必须正确响应 Access-Control-Allow-Headers,否则你的自定义头(比如 Authorization)会被拦下。

比如你在请求里加了个 X-Client-Version 来标识版本号,服务端就得允许这个字段:

Access-Control-Allow-Headers: Content-Type, Authorization, X-Client-Version

别乱加无意义的头

有些开发者为了“保险”,把各种头都加上,甚至复制一堆无关的 header。这不仅增加请求体积,还可能触发安全策略拦截。该用的用,不该用的别凑热闹。

调试建议

遇到接口返回 400 或 401,别急着查参数,先看请求头对不对。用浏览器开发者工具或 Postman 检查一下,很多时候问题就出在少了个 Content-Type 或者 token 拼错了。

实际项目中,见过因为大小写写错导致失败的案例:content-type 虽然看起来没问题,但某些严格服务端只认标准写法 Content-Type。虽然 HTTP 头本身不区分大小写,但规范写法更稳妥。