Web 服务器与网关 / 系统课时
规划域名和请求路径结构
规划域名和请求路径结构
配置入口之前,先约定哪些请求属于前端、哪些属于资源和 API,能够减少后续回退、缓存和代理规则互相干扰。本篇为同一域名建立路径契约,明确 API 是否保留前缀,并给不存在资源和未知域名安排可验证的行为。
学习目标
- 为页面、资源与 API 分配清晰的路径边界。
- 明确转发后的 URI、错误行为和缓存责任。
- 用请求矩阵指导后续实现和验收。
一个域名划分三类请求
本章实验使用 app.test,HTTP 回环 8080、HTTPS 回环 8443;生产应替换成自己控制的域名和对应标准端口。app.test 不要求公网解析,实验通过 curl --resolve 指向本机。

| 范围 | 约定 |
|---|---|
| /assets/ | 只找构建资源,缺失返回 404 |
| /api/ | 后端路由本身包含 /api/,转发时保留 |
| /account 等页面路径 | 由 SPA 入口加载后交给前端路由 |
| /api | 明确跳转到 /api/,保留查询参数 |
| 未知 Host | 使用明确的默认站点拒绝 |
同域名可以简化浏览器跨域关系,但认证、CSRF、Cookie 范围和应用授权仍需单独设计。后端端口不应成为用户绕过入口的公开通道。
把约定写成待实现配置
以下是 http 内的片段示例,用于审阅路径契约。依赖后续课准备的 /tmp/nginx-web-entry 文件目录和回环 9001 后端;目前不是可直接上线的完整部署:
server {
listen 127.0.0.1:8080 default_server;
server_name _;
return 404;
}
server {
listen 127.0.0.1:8080;
server_name app.test;
root /tmp/nginx-web-entry;
location = /api { return 308 /api/$is_args$args; }
location ^~ /api/ { proxy_pass http://127.0.0.1:9001; }
location ^~ /assets/ { try_files $uri =404; }
location / { try_files $uri $uri/ /index.html; }
}预期生效行为:API 的 proxy_pass 不带 URI 部分,保留 /api/ 路径;资源不存在时 404;前端页面路径才允许回退。后续部署后要按表逐项请求验证,而非只验证首页。
先明确 URI 与缓存语义
若后端实际只识别 /health,是否去掉 /api 前缀必须重新约定,不能碰巧增加一个斜线来尝试修复。还要考虑查询参数、编码路径、尾部斜线和非 GET 方法,避免前端和应用对同一路径产生不同解释。
带内容哈希的资源可以长缓存,入口 HTML 应及时重新验证,以便引用新资源;API 是否缓存需按认证与业务语义决定。不要把全站所有 200 都设为一年缓存。
建立上线前验收矩阵
实现后至少测试根路径、一个前端深层路由、实际脚本、缺失脚本、正确 API、未知 API 和未知 Host。记录预期状态、Content-Type、正文标记和实际转发 URI。
再加入 HTTP 到 HTTPS 的目标、证书域名与多实例入口。路径约定改变时同步更新前端请求地址、后端路由、监控和文档;清楚的契约能让排查首先回答“这个请求应该由谁处理”。