HTTP Authorization 头几乎每个做后端、做接口联调的人都跟它打过交道但很少有人真正把它讲透。我第一次被它坑是联调时反复收到 401查了半天才发现 token 前少了 Bearer 后面的空格。后来系统地看了 RFC又踩了不少生产环境的坑才算是把这一个头玩明白。这篇文章我想从一个从业者的角度把 Authorization 头的基础知识完整梳理一遍它背后的 HTTP 认证框架是什么、常用的认证方案怎么写、真实请求长什么样、出了问题该怎么排查。内容不追求高深但足够让你以后遇到 401、502、跨域、网关透传这类情况时心里有数知道往哪个方向查。适合后端工程师、全栈开发者也适合刚接触接口调试的新手。1. Authorization 头到底在做什么1.1 它背后的 HTTP 认证框架Authorization 头不是凭空来的它属于 HTTP 协议定义的认证框架核心文档是 RFC 7235后来被 RFC 9110 更新。这套框架特别简单就两个角色、三个报文头服务端想要拦住未认证的请求就返回401 Unauthorized并在响应里带上WWW-Authenticate头告诉客户端“我这里用什么认证方案”。客户端拿到提示之后在下一个请求里带上Authorization头里面放入对应的凭据。如果服务端还需要进一步告诉客户端“当前凭据不被接受”还可以用Authentication-Info头但日常调试中见到的不多。整个交互模型可以用一次典型的 Basic 认证流程来理解客户端请求 - 服务端返回 401 WWW-Authenticate: Basic realmadmin 客户端带上 Authorization: Basic xxx - 服务端校验通过 - 返回 200这里有个关键点401不只是一个“没权限”的报错它是服务端发起的认证挑战。很多新手一看到 401 就以为 token 错了其实更准确的做法是先看响应里的WWW-Authenticate头它直接告诉你了服务端想要什么格式的凭据。我排查过很多 401 问题最后发现是服务端要求 Basic客户端却给了 Bearer两边根本不在一个频道上。Authorization 头的语法定义也不复杂credentials auth-scheme [ 1*SP ( token68 / #auth-param ) ]。翻译成人话就是“认证方案 空格 凭据内容”。这个结构一定要记牢后面所有的问题排查都围绕这个语法展开。比如Authorization: Bearer eyJhbGci...Bearer是 scheme后面的字符串是凭据Authorization: Basic YWRtaW46MTIzNDU2Basic是 scheme后面是 base64 编码的用户名密码。1.2 和 Cookie、Token 的边界很多初学者会混淆既然 Cookie 也能存登录态为什么 API 要用 Authorization 头关键在于职责边界不同。Cookie 是浏览器自动管理的会话状态它会自动随请求携带服务端通过 session 在内存或存储里保存用户状态。而 Authorization 头是无状态的客户端在每次请求时主动把凭据放进去服务端不保存会话只做校验。举一个实际场景一个纯后端 API 服务如果依赖 Cookie那客户端就必须支持 Cookie 存储机制移动端、脚本、服务间调用都得很小心地处理如果换成 Authorization 头带 Bearer token任何能发起 HTTP 请求的客户端都只需要拼一个请求头跨域问题也更好控制第三方授权也更方便。所以现代 API 设计几乎清一色选择 Authorization。但无状态也有代价凭据泄露就等于账号泄露。Cookie 有浏览器同源策略保护而 Authorization 头里的 token 一旦被中间人抓取对方可以直接冒充你发起请求。所以我的原则很简单公网上传输 Authorization 头必须走 HTTPS调试日志里绝不打完整的 token截屏分享请求信息时先遮住 Authorization。2. 常见认证方案细节拆解2.1 Basic最朴素也最容易被误用的方案Basic 认证是最老的方案格式一句话就能说清Authorization: Basic base64(username:password)。注意base64 是编码不是加密。任何人拿到YWRtaW46MTIzNDU2都可以直接解出admin:123456。我在之前的文章里反复强调过不要因为看到一串看不懂的字符就觉得安全。所以 Basic 认证必须跑在 HTTPS 上否则等于把密码明文挂在网上。生成这个头的方法也很简单命令行一条命令echo -n admin:123456 | base64 # 输出 YWRtaW46MTIzNDU2反过来解码echo YWRtaW46MTIzNDU2 | base64 -d # 输出 admin:123456Basic 认证会配合WWW-Authenticate: Basic realmxxx使用。这里的realm表示保护领域浏览器弹窗里会显示给用户看服务端可以用它区分不同区域的认证。什么场景还在用 Basic最常见的是内部工具、一次性调试、老设备管理页面以及一些只在内网使用的接口。我在实际工作中用 Basic 最多的地方反而是本地调试服务比如给测试环境接口加一层最简单的访问控制。公网 API 如果还在用 Basic我建议立刻换掉。调试技巧curl的-u参数会自动帮你生成 Basic 头不用手写 base64curl -u admin:123456 http://api.example.com/resource2.2 BearerOAuth2/JWT 时代的默认选择现在最常见的 API 认证方式是 Bearer token格式是Authorization: Bearer token注意 Bearer 和 token 之间有一个空格。Bearer这个词的意思是“持有者”也就是“谁拿着这个 token谁就是被授权的人”。它不关心 token 本身是什么格式可以是 JWT也可以是不透明字符串。JWT 的好处是服务端不用查库直接验签就能拿到用户身份和过期时间不透明 token 的好处是可以随时在服务端吊销。OAuth2 的访问令牌通常用 Bearer 方式传给 API。比如授权码流程拿到access_token之后请求用户信息接口就写成curl -H Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c \ http://api.example.com/userinfo用 Bearer 有一个非常容易踩的坑漏掉空格、写错大小写、token 里多带引号。Bearer eyJ...和BearereyJ...是完全不一样的东西有些客户端复制 token 时把引号也带上了服务端验证直接失败。我见过一个线上事故就是上游服务拼接 header 时用了Bearer${token}少了一个空格结果所有请求 401排查了很久才找到。Bearer token 的过期管理也很重要。JWT 里通常带exp字段客户端不能只看响应状态码而是要在请求前判断 token 是否快过期了提前用 refresh token 刷新。否则就会陷入“401 - 刷新 - 重放请求”的循环。2.3 Digest、API Key、签名认证那些“非主流”但常见的写法除了 Basic 和 Bearer还有几种实际场景中会遇到的认证方案。Digest 摘要认证基于挑战响应的思路服务端下发一个随机数 nonce客户端把用户名、密码、nonce、请求方法等信息做哈希再把结果传回去这样密码不会直接在网络上明文传输。协议现在主要是 RFC 7616。但它的弱点也明显如果中间人完整接管了 HTTP 连接防御效果有限。现在 Web 场景用得少但在嵌入式设备、局域网硬件管理接口里还能见到适合不想明文传密码、又没条件上 TLS 的环境。API Key是很多开发者门户和老系统的做法。它没有统一标准有的用Authorization: ApiKey xxxxx有的用X-API-Key: xxxxx还有的直接放 query 参数。优点是真的简单缺点是服务端要存完整的密钥而且这种 key 一般没有过期的概念一旦泄露很难收场。我建议只在内部服务间调用、或者对安全要求不高的场景使用公网开放 API 至少要用有过期机制的 Bearer token。签名认证是另一类思路最典型的就是Authorization: AWS4-HMAC-SHA256。格式通常类似Authorization: AWS4-HMAC-SHA256 CredentialAKID/20240101/us-east-1/service/aws4_request, SignedHeadershost;x-amz-date, Signaturexxxx这类认证不只是传一个 token而是把请求方法、请求路径、请求体摘要、时间戳一起做签名服务端用同样的密钥和算法重算一遍比对签名是否一致。好处是能防篡改、防重放比单纯传 token 安全得多。很多云厂商 SDK 和开放平台签名都采用这种思路。排查这类问题时常见原因集中在系统时间不准、签名有效期过了、请求体哈希没包含对位置。2.4 一张表格看懂如何选型方案请求头示例凭据内容安全级别典型场景常见坑BasicBasic YWRtaW46MTIzNDU2base64(用户名:密码)低必须配合 HTTPS内网工具、调试、老设备误以为 base64 是加密BearerBearer eyJhbGci...JWT 或不透明 token中高取决于 token 策略OAuth2、现代 API漏空格、token 过期未刷新DigestDigest usernameadmin, realmx, nonce...哈希摘要中防明文不防劫持嵌入式环境算法和 qop 不匹配API KeyApiKey xxxxx或X-API-Key: xxxxx静态密钥低内部服务、开发者门户无法吊销、容易泄露签名认证AWS4-HMAC-SHA256 Credential...请求签名高云服务 SDK、开放平台时间不同步、签名内容不完整选型逻辑并不复杂临时调试用 Basic标准 API 用 Bearer设备协议考虑 Digest内部简单服务用 API Key对外云服务尽量用签名认证。3. 从请求发起到排查的完整实战3.1 用 curl 手动构造 Authorization 请求调试接口时curl 是我最常用的工具因为它能把最原始的请求头看得清清楚楚。三种常见调试方式# 方式一手动加 header curl -i -H Authorization: Bearer eyJhbGciOiJIUzI1NiJ9... http://api.example.com/resource # 方式二让 curl 自动处理 Basic curl -i -u admin:123456 http://api.example.com/resource # 方式三Digest 认证 curl -i --digest -u admin:123456 http://api.example.com/resource这里-i的作用是显示响应头强烈建议调试时带上因为你会看到WWW-Authenticate的具体内容。我通常的做法分三步先不带任何认证请求一次看 401 响应里的WWW-Authenticate提示什么方案再按提示手动带上 Authorization 请求最后确认响应从 401 变 200问题就定位了。浏览器开发者工具也能辅助排查。打开 Network 面板点击请求在 Request Headers 里看到浏览器实际发送的 Authorization。这里提醒一句如果你要在网上提问或者截屏分享务必把 Authorization 的值遮掉我见过不少人截图时把 token 直接暴露在公网上几分钟后账户就被盗用了。3.2 各种客户端代码里的标准写法实际写代码时不同语言处理 Authorization 的方式略有差异。JavaScript 的 fetchfetch(http://api.example.com/resource, { headers: { Authorization: Bearer ${token}, }, });Axios 我更习惯用请求拦截器统一加这样不用每个请求都写一遍api.interceptors.request.use((config) { config.headers.Authorization Bearer ${getToken()}; return config; });Python requests 库有两种写法# Bearer requests.get(url, headers{Authorization: fBearer {token}}) # Basic requests.get(url, auth(admin, 123456))Java Feign 则通常通过 RequestInterceptor 往请求里塞 header但这里有一个隐藏问题如果你用的是 Feign 的 URL 直连token 还能正常透传如果中间有网关或者多个服务链路token 可能会在某一层丢失。热搜里有一条feign.FeignException$InternalServerError: [500] during [GET] to [http://item...]很多时候不是下游服务挂了而是下游收不到 Authorization直接 401但网关层把 401 包装成了 500。我在 Go 里通常是这样加的req, _ : http.NewRequest(GET, url, nil) req.Header.Set(Authorization, Bearer token)不管用什么语言我的几条代码规范是token 不写死在代码里从环境变量或配置中心读取日志里禁止打印 Authorization 头的完整值记录日志时只保留 scheme 和 token 前四位。3.3 一个从 401 到 200 的排查实录前面讲了一堆理论这里用一个相对完整的排查案例收拢一下思路。背景调用内部接口时返回401 {code:30014,message:token is invalid.}。看到这个报错别急着改代码按顺序排查第一步确认服务端期望的认证方案。用 curl 请求一次看响应头里有没有WWW-Authenticate。有的服务端直接报了 token invalid反而没有提示那就去看接口文档。如果文档说用 Bearer而客户端传了 Basic那就是方案不匹配。第二步确认 token 是不是真的失效了。如果 token 是 JWT可以解码看exp字段如果是 opaque token问一下授权服务的签发时间。很多 token invalid 其实就是过期了尤其测试环境 token 有效期短更容易遇到。第三步检查拼接格式。把 Authorization 的完整值打印出来肉眼检查有没有多余空格、换行、引号。Bearer后面是一个空格不要把引号一起粘进去。第四步看服务端日志。这一步能区分是网关层丢了 header还是业务层拒绝认证。比如用 Nginx 做反代时如果配置里没显式透传Authorization 是有可能被吞掉的。正确配置是proxy_set_header Authorization $http_authorization;如果经过网关后 header 还在但业务服务里读不到那就要检查服务框架的 header 大小写处理逻辑了。HTTP 规范里 header 名不区分大小写但有些框架在取 header 时写死了小写或首字母大写导致匹配不上。整套排查结束之后我一般会把最原始的 curl 命令保存成一个调试脚本下次遇到类似问题直接改参数重放效率会高很多。4. 常见问题与避坑清单4.1 高频报错速查表报错现象可能原因排查方向401 token is invalidtoken 过期、格式错误、被吊销检查 JWT exp、检查 header 拼接401 WWW-Authenticate: Basic服务端要求 Basic客户端给了 Bearer按响应头指示改用对应方案400 Invalid character found in method name请求行或 header 被污染、代理加了错误内容抓包看原始请求检查是否拼接了换行符502 Bad Gateway网关到上游连接失败或超时检查上游服务、网关转发规则、Authorization 是否透传403 Forbidden认证通过但权限不足检查 scope、角色、操作权限跨域请求失败CORS 预检未通过服务端加上 Access-Control-Allow-Headers: Authorization这里重点说一下热搜里的502 Bad Gateway。很多人一看到 502 就以为是服务端挂了但其实它和 Authorization 的关联也很大网关层在转发请求时如果重新构造了 header而没有把原请求的 Authorization 带上上游就会返回 401某些网关看到上游 401 后又不会原样透传而是直接包装成 502。所以看到 502先查两条链路网关到上游的网络连通性以及网关转发的 header 白名单。4.2 容易被忽略的四个细节第一个细节是日志脱敏。尤其是在排查问题时很多人直接logger.info(request.getHeader(Authorization))把完整 token 打到日志里然后日志系统又被其他团队共享。Token 一旦进了日志泄露面就被无限放大。我自己在代码里会写一个脱敏方法只保留Bearer AB12****这样的格式够排查用也不会泄露完整凭据。第二个细节是断点续传和多线程下载。这类需求里请求头不仅有 Authorization还有 Range。有些下载工具做分片时会在内部创建多个请求每个请求都要带上同一个 token如果某个分片请求丢了 Authorization服务端返回 401客户端又没做好重试整个下载直接失败。检查的时候别只盯着主请求分片请求的 header 也要看。第三个细节是 Authorization 头的 CORS 预检。浏览器跨域请求只要带了非简单头就会先发一个 OPTIONS 预检请求。Authorization 属于非简单头所以服务端必须响应Access-Control-Allow-Headers: Authorization否则浏览器会直接拦截表现像是接口调用失败。很多前端同学在这个问题上折腾很久其实问题根本不在业务接口而在网关或 Nginx 的 CORS 配置。第四个细节是不要把 Authorization 头和业务 token 混为一谈。有些团队会在 Body 里传 token同时又用 Authorization 传认证信息两套体系叠加排错的时候特别容易混淆。我的建议是职责分开认证走 Authorization业务级的资源令牌、临时口令放 Body 或自定义头并且接口文档里写清楚。结尾说回我自己的心得。这几年调过的接口里Authorization 相关的问题其实占了不少比例大多不是难破的问题而是容易忽略的基础细节空格、大小写、过期时间、方案不匹配。我现在拿到一个接口第一件事永远是看文档里要求的 scheme然后用 curl 带-i请求一次确认WWW-Authenticate的提示再写业务代码。还有一个习惯是环境变量里放 token所有调试脚本都引用变量而不是硬编码避免 token 散落在各个文件里。如果你也是经常跟 API 打交道的人建议把本文涉及的几个检查项记下来遇到 401 先别慌按照“方案 - 格式 - 时效 - 链路”的顺序查一遍绝大多数问题都能快速定位。Authorization 头算不上复杂但把基础打扎实了后面处理 OAuth2、网关鉴权、签名认证这些进阶内容都会顺畅很多。