xs.json 全解 · 服务级字段

本章导读

7.1 引入

配置系统的常见病有两种：一是松——拼错的字段被静默忽略，直到线上才发现；二是散——行为散落在配置、环境变量、命令行三处。xs.json 的对策是 fail-fast + 单一来源：所有预设字段非法都在启动时点名退出，所有未预设字段原样进 Custom 留给应用——宿主不认识的字段永远不会被吞掉，也永远不会被猜错含义。

7.2 五类协议（class）

白名单之外的值直接 fail-fast。选类的判断标准很简单：浏览器能说的用 http/ws，字节流用 tcp，无连接用 udp，其余自己来。

7.3 端点字段

{
    "ip": "0.0.0.0",        /* 监听地址，默认全网卡 */
    "port": 80,             /* 明文端口，非 custom 必填 */
    "tls": true,            /* 开 TLS 端口；udp 禁止 */
    "port_tls": 443,        /* 默认 443；与明文端口同 IP 冲突即拒 */
    "ip_tls": "0.0.0.0"     /* 缺省复用 ip */
}

刚才发生了什么：一个服务最多两个端点（明文 + TLS）。冲突规则是启动期检查——同 IP 上明文端口与 TLS 端口撞车直接拒绝，不会出现"后者覆盖前者"的静默行为。证书路径不在服务级：它在 host 级（第 8 章展开），服务级只管"要不要 TLS 端口"。

7.4 限额字段

recv_limit 是内存防线：一次读进来的数据量上限。tcp 上它影响单连接的缓冲峰值；udp 上数据报天然 ≤64KB，所以上限收紧到 65535。请求级的 header/body 限额不在服务级预设字段里——它们是 Custom 旋钮（第 9 章），由 http 驱动读取。

7.5 服务级脚本缺省

五个脚本相关字段可以写在服务级，作为所有 host 的缺省：

{
    "class": "http",
    "name": "my-site",
    "port": 8080,
    "path": "wwwroot",       /* 静态根 */
    "devlang": "c",          /* 脚本语言 */
    "devfile": "main.c",     /* 脚本入口 */
    "dev_inc": "includes",   /* 额外头目录（分号分隔） */
    "dev_lib": "librarys"    /* 额外库目录 */
}

未配置 host_default 时，这五个字段合成出 DefaultHost——这就是第 4 章最小应用不需要写 host_default 的原因。host 级出现同名字段时逐项覆盖。

7.6 契约

• 校验线：class 白名单、port 1–65535、tls×udp 互斥、端口冲突——全部启动期点名 fail-fast。
• 缺省线：服务级脚本字段只是 host 级的缺省源，不是第二套配置。
• 唯一性线：name 全局唯一——它是运行期 xsServerFind 的键，也是 reload 的目标描述。

常见错误

{ "ip": "0.0.0.0", "port": 8080,
  "tls": true, "port_tls": 8080 }

{ "ip": "0.0.0.0", "port": 8080,
  "tls": true, "port_tls": 8443 }

{ "class": "udp", "port": 9000,
  "tls": true }

{ "class": "udp", "port": 9000 }

编程练习