Web 服务器与网关 / 系统课时
用 proxy_pass 转发 API 请求
用 proxy_pass 转发 API 请求
本篇把一个本机 Python API 放到 Nginx 后面,用健康检查和创建订单两次请求验证路径、方法与请求体。最终能够分清“代理连不上后端”和“后端已经返回业务错误”,并按顺序定位失败位置。
学习目标
- 配置保持
/api/路径的基本 HTTP 代理。 - 用 GET 和 POST 验证上游方法、状态码与 JSON 请求体。
- 根据直连结果和代理结果区分连接问题与业务返回。
先让后端独立响应
在 Linux 实验机上把以下完整程序保存为 api_server.py,使用 Python 3 执行 python3 api_server.py。它只绑定本机 9000,负责教学用健康检查和固定订单回显,不包含数据库、登录或生产级输入限制。
import json
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
class API(BaseHTTPRequestHandler):
def reply(self, status, value):
payload = (json.dumps(value, separators=(",", ":")) + "\n").encode()
self.send_response(status)
self.send_header("Content-Type", "application/json")
self.send_header("Content-Length", str(len(payload)))
self.end_headers()
self.wfile.write(payload)
def do_GET(self):
if self.path == "/api/health":
self.reply(200, {"ok": True})
else:
self.reply(404, {"error": "not-found"})
def do_POST(self):
if self.path != "/api/orders":
self.reply(404, {"error": "not-found"})
return
try:
# 本例 curl 提供 Content-Length;只接受 JSON 对象中的字符串 item。
raw = self.rfile.read(int(self.headers.get("Content-Length", "0")))
value = json.loads(raw)
if not isinstance(value, dict) or not isinstance(value.get("item"), str):
raise ValueError("item required")
except (ValueError, TypeError):
self.reply(400, {"error": "invalid-json-or-item"})
return
self.reply(201, {"id": 7, "item": value["item"]})
if __name__ == "__main__":
ThreadingHTTPServer(("127.0.0.1", 9000), API).serve_forever()预期结果:进程前台等待请求;GET /api/health 返回 200 和 {"ok":true},POST /api/orders 携带 {"item":"book"} 返回 201 和固定编号 7。固定编号方便检查代理行为,不表示真实创建了订单。
先在另一终端执行 curl -sS http://127.0.0.1:9000/api/health,预期输出 {"ok":true}。直连都失败时,应先检查进程和监听地址,不要立即修改 Nginx。
把完整 API 路径交给后端
以下是 http 上下文内的站点片段示例;依赖上一段程序正在本机 9000 运行,以及空闲的 8080 端口:
server {
listen 127.0.0.1:8080;
server_name api-proxy.test;
location /api/ {
# 后端路由本身带 /api/,因此不附加会替换前缀的 URI。
proxy_pass http://127.0.0.1:9000;
proxy_set_header Host $host;
}
location / { return 404; }
}proxy_pass 指定上游地址。这里不使用 proxy_method、不关闭请求体转发,所以 POST 仍是 POST,JSON 内容会交给后端。配置检查成功并 reload 后,先测试健康接口,再测请求体。
# 分别验证 GET 和 POST;-d 的内容由单引号保护,不经 Shell 展开。
curl -sS -H 'Host: api-proxy.test' -w 'status=%{http_code}\n' http://127.0.0.1:8080/api/health
curl -sS -H 'Host: api-proxy.test' -H 'Content-Type: application/json' -d '{"item":"book"}' -w 'status=%{http_code}\n' http://127.0.0.1:8080/api/orders预期输出:
{"ok":true}
status=200
{"id":7,"item":"book"}
status=201用失败请求确认边界
把 POST 请求体换为 {},预期收到后端的 400 和 {"error":"invalid-json-or-item"}。代理没有自动把输入改成合法订单。GET /api/missing 应收到后端的 404 JSON;GET /other 则在本例入口直接返回 404,后端不会收到它。
遇到 502,先在 Nginx 所在机器请求 9000,再看 error.log 的连接错误;遇到本例的 JSON 404,说明已经连到后端,应检查路径与路由。请求体过大还可能先被 Nginx 拒绝,不能只看后端是否打印了日志来认定请求从未发出。
proxy_set_header Host $host 给后端传规范化的站点主机名。如果后端要求某个固定虚拟主机名称,应按它的路由要求设置;HTTPS 上游还涉及独立的 TLS 名称与证书验证,不能仅靠改 HTTP Host 完成。本例只演示本机 HTTP API,不代替生产部署验收。