3.5 KiB
3.5 KiB
ADDED Requirements
Requirement: HTTP method 语义
系统 SHALL 为运行时端点提供明确的 HTTP method 语义，避免不支持的 method 被错误地当作成功请求处理。
Scenario: GET 请求访问运行时端点
- WHEN 客户端使用
GET请求/health或/api/demo - THEN Bun server SHALL 返回对应端点的成功响应
Scenario: HEAD 请求访问运行时端点
- WHEN 客户端使用
HEAD请求/health或/api/demo - THEN Bun server SHALL 返回与
GET相同的成功状态和 headers，但 MUST NOT 返回响应体
Scenario: 不支持的 method 访问运行时端点
- WHEN 客户端使用不支持的 method 请求
/health或/api/demo - THEN Bun server MUST 返回 JSON 405 响应，并带有描述允许 method 的
Allowheader
Requirement: 运行配置校验
系统 SHALL 对运行时 host 和 port 配置提供稳定、可测试的解析与校验行为。
Scenario: 使用默认运行配置
- WHEN 未提供 host 或 port 覆盖
- THEN server SHALL 使用 README 文档化的默认 host 和 port
Scenario: CLI 参数优先于环境变量
- WHEN CLI 参数和环境变量同时提供同一项运行配置
- THEN server SHALL 使用 CLI 参数中的值
Scenario: 拒绝无效端口
- WHEN port 配置不是整数、小于 0 或大于 65535
- THEN server MUST 拒绝启动并报告无效端口
Scenario: 接受端口边界值
- WHEN port 配置为 0 或 65535
- THEN server SHALL 将其作为有效端口配置处理
Requirement: API 错误响应一致性
系统 SHALL 为 API 命名空间内的错误返回机器可读 JSON 响应。
Scenario: 未知 API 路由
- WHEN 客户端请求未知的
/api/*路由 - THEN Bun server MUST 返回包含
error和status字段的 JSON 404 响应，而不是前端 HTML 文档
Scenario: API method 不允许
- WHEN 客户端使用不支持的 method 请求已存在的 API 路由
- THEN Bun server MUST 返回包含
error和status字段的 JSON 405 响应
Requirement: 生产缓存策略
系统 SHALL 为生产静态资源和前端入口 HTML 使用明确的缓存策略。
Scenario: 请求前端入口 HTML
- WHEN 生产 Bun server 返回前端入口 HTML 文档
- THEN 响应 SHALL 使用
Cache-Control: no-cache
Scenario: 请求构建后的静态资源
- WHEN 生产 Bun server 返回 Vite 构建后的静态资源
- THEN 响应 SHALL 使用长缓存策略
public, max-age=31536000, immutable
Scenario: 请求未知静态资源
- WHEN 客户端请求不存在的
/assets/*资源或带文件扩展名的未知路径 - THEN Bun server MUST 返回 404，且 MUST NOT 返回前端入口 HTML 文档
Requirement: 低风险安全响应头
系统 SHALL 在生产运行时响应中附加低风险安全响应头，提升基础安全性且不提前约束未来前端资源策略。
Scenario: 生产 HTML 响应包含安全头
- WHEN 生产 Bun server 返回前端 HTML 文档
- THEN 响应 SHALL 包含
X-Content-Type-Options: nosniff和Referrer-Policyheaders
Scenario: 生产 JSON 响应包含安全头
- WHEN 生产 Bun server 返回
/health或/api/*JSON 响应 - THEN 响应 SHALL 包含
X-Content-Type-Options: nosniff和Referrer-Policyheaders
Scenario: 生产静态资源响应包含安全头
- WHEN 生产 Bun server 返回 Vite 构建后的静态资源
- THEN 响应 SHALL 包含
X-Content-Type-Options: nosniff和Referrer-Policyheaders