python原生grpcio不支持http/1.1+json网关，需用go的grpc-gateway代理或fastapi手动桥接；servehttp仅支持grpc-web，非rest/json接口，且无路径映射、openapi、鉴权等能力。
Python 原生 grpcio 不支持 HTTP/1.1 + JSON 网关功能，必须引入外部代理层（如 grpc-gateway）或改用其他语言实现网关。直接在 Python 服务中用 http.ServeHTTP 暴露 gRPC 服务，只会得到 HTTP/2 的 gRPC-Web 兼容端点，不是真正的 REST/JSON 接口。
为什么不能只靠 Python 的 http.Server 实现双协议
有人尝试用 grpc.Server.ServeHTTP 把 gRPC 服务挂到 http.ServeMux 下，以为能同时响应 HTTP 请求——这是常见误解。该方法仅支持 gRPC-Web 协议（需前端额外加 grpc-web 客户端库），且要求客户端发的是二进制 gRPC over HTTP/2 或 HTTP/1.1 + base64 编码，不接受普通 JSON body、不解析 URL 路径参数、不自动映射 GET /books/123 到 GetBook(id=123)。
-
ServeHTTP是调试/测试用途，不是生产级 HTTP/JSON 网关 - 它不读取
google.api.http注解，无法做路径/方法/参数映射 - 返回仍是 Protobuf 二进制或 gRPC-Web 格式，不是可读 JSON
- 没有请求校验、OpenAPI 文档、CORS、鉴权中间件等 REST 网关基础能力
正确做法：用 Go 写 grpc-gateway 代理层
目前最成熟、文档最全的方案是用 Go 编写 grpc-gateway 作为反向代理，Python 只负责纯 gRPC 服务端。这是 Google Cloud Endpoints Bookstore 示例采用的方式，也是生产环境事实标准。
- Python 服务监听
localhost:50051（gRPC 端口），只处理二进制 Protobuf 请求 - Go 编写的
grpc-gateway监听:8080，解析bookstore.proto中的google.api.http注解，把GET /v1/shelves映射为ListShelves()调用 - 所有 JSON ↔ Protobuf 编解码、错误码转换（如 gRPC
NOT_FOUND→ HTTP 404）、Header 透传均由 Go 侧完成 - 前端 curl 或 axios 直接调用
http://localhost:8080/v1/shelves，无需任何 gRPC 客户端
关键配置在 bookstore.proto 中，例如：
service BookStore {
rpc ListShelves(ListShelvesRequest) returns (ListShelvesResponse) {
option (google.api.http) = {
get: "/v1/shelves"
};
}
}
替代方案：Python 中用 fastapi 手动桥接（仅限小规模）
若必须全 Python 技术栈，可用 fastapi + grpcio 手动封装一层 REST 接口，但属于“重复造轮子”，不推荐用于生产。
- 每个 gRPC 方法都要手动写一个 FastAPI 路由，例如
@app.get("/v1/shelves")→ 构造ListShelvesRequest→ 调用stub.ListShelves() - 需自行处理 JSON ↔ Protobuf 转换（用
json_format.MessageToJson）、状态码映射、分页参数提取、错误包装 - 无法复用
google.api.http注解，路由定义和 proto 脱节，后期维护成本高 - 性能不如 Go 的
grpc-gateway（后者编译为原生二进制，无解释器开销）
真正容易被忽略的一点：网关和 gRPC 服务必须部署在同一网络域（如 Docker 同一 network 或 Kubernetes 同 namespace），否则 grpc-gateway 无法稳定连接 Python 的 gRPC 服务端——DNS 解析失败、TLS 证书不匹配、防火墙拦截这三类问题占实际联调故障的 70% 以上。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
