grpc服务端需通过grpc.unaryinterceptor拦截请求并校验token或api key，从ctx取metadata.md后用md.get("authorization")提取bearer token，失败返回status.error(codes.unauthenticated)，jwt解析推荐github.com/golang-jwt/jwt/v5，客户端须用metadata.appendtooutgoingcontext传token，确保interceptor生效且header未被中间件过滤。
gRPC服务端如何接入自定义认证逻辑
gRPC本身不内置Token或API Key校验，必须靠 grpc.UnaryInterceptor 或 grpc.StreamInterceptor 拦截请求，在业务逻辑前做身份检查。绕过拦截器直接写在Handler里，等于把认证逻辑和业务耦合，后续没法复用或统一管控。
常见错误是只校验Header但忽略大小写——HTTP/2 Header默认小写，metadata.MD 里的键全被转成小写，所以用 md.Get("authorization") 而不是 md.Get("Authorization")。
- 推荐用
grpc.UnaryInterceptor，90%场景是简单RPC调用，比Stream更轻量 - 从
ctx中取metadata.MD，再用md.Get("authorization")提取Bearer Token - 若用API Key，建议固定键名如
md.Get("x-api-key")，避免和标准Header冲突 - 校验失败必须返回
status.Error(codes.Unauthenticated, "invalid token")，不能只 return nil err
Token解析与验证该用哪个库
别自己手写JWT解析。Go生态里 github.com/golang-jwt/jwt/v5 是当前最稳的选择，v4 已归档，v5 支持Context超时、更严格的alg校验，且明确弃用不安全的 SigningMethodNone。
容易踩的坑：用 ParseWithClaims 但没传入 *jwt.Token 的指针，导致claims始终为空；或者用错key类型——HS256用字符串密钥，RSA用 *rsa.PrivateKey / *rsa.PublicKey，混用会 panic。
立即学习“go语言免费学习笔记（深入）”；
- HS256场景下，密钥长度至少32字节，短密钥会被拒绝（
key is not valid错误） - 解析时务必传
jwt.WithValidator(&validator)，否则过期时间（exp）不会自动校验 - 别在验证函数里做网络请求（比如查DB），否则每个RPC都拖慢，应预加载或用缓存
客户端怎么正确传Token
客户端不是简单加个Header就行。gRPC的metadata必须通过 grpc.CallOption 注入，用 grpc.Header 或 grpc.Trailer 都不对——它们是服务端回传用的。
典型错误：用 ctx = context.WithValue(ctx, "token", "xxx")，这根本传不到服务端；或者用 metadata.Pairs("Authorization", "Bearer xxx") 却忘了调用 grpc.Header 选项，结果服务端收不到。
- 必须用
metadata.AppendToOutgoingContext(ctx, "authorization", "Bearer xxx") - 如果Token需要动态刷新，别在每次RPC前重新Append，而应在Interceptor里统一处理
- 测试时可用
grpc.WithInsecure()+grpc.WithBlock()确保连接建立成功，避免因TLS握手失败掩盖认证问题
为什么有些请求总被跳过认证
不是所有方法都会进你写的Interceptor。gRPC允许对特定方法绕过拦截器，比如健康检查 /grpc.health.v1.Health/Check，或者你手动在 grpc.Server 初始化时用了 grpc.UnknownServiceHandler，这类请求根本不会触发UnaryInterceptor。
另一个高发原因是：注册服务时用了 RegisterXXXServer 但没传入带Interceptor的 grpc.Server 实例，而是用了默认无拦截器的server，结果整个服务都没认证。
- 检查
grpc.Server创建时是否传了grpc.UnaryInterceptor(interceptor) - 确认健康检查、反射等内置服务是否被显式排除（如用
grpc.Creds时未配TLS，某些代理会丢Header） - 用
grpcurl -plaintext -H "authorization: Bearer xxx" localhost:8080 list手动测，比写客户端更快定位是Client还是Server问题
认证链上最脆弱的一环往往不在Token解析，而在上下文传递是否完整、Interceptor是否生效、以及Header是否被中间件（如Nginx、Envoy）悄悄过滤或重写。这些地方不打日志，问题就藏得深。
