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,负责教学用健康检查和固定订单回显,不包含数据库、登录或生产级输入限制。

python
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 端口:

nginx
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 后,先测试健康接口,再测请求体。

bash
# 分别验证 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

预期输出:

text
{"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,不代替生产部署验收。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

用 proxy_pass 转发 API 请求

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通