3.3 KiB
3.3 KiB
ADDED Requirements
Requirement: 网关层代理错误使用应用统一格式
系统 SHALL 对代理接口中由网关自身产生的错误使用应用统一错误响应格式。
Scenario: 标准网关错误格式
- WHEN 代理接口返回网关层错误
- THEN SHALL 使用以下 JSON 格式：
{ "error": "错误描述", "code": "ERROR_CODE" } - THEN
error字段 SHALL 包含人类可读的错误描述 - THEN
code字段 SHALL 包含机器可读的错误码
Scenario: 网关错误码集合
- WHEN 代理接口返回网关层错误
- THEN code SHALL 使用以下枚举之一：
INVALID_JSON、INVALID_REQUEST、INVALID_MODEL_ID、MODEL_NOT_FOUND、PROVIDER_NOT_FOUND、UNSUPPORTED_INTERFACE、UNSUPPORTED_MULTIMODAL、CONVERSION_FAILED、UPSTREAM_UNAVAILABLE
Requirement: 代理接口上游错误透传
系统 SHALL 对代理接口中已经收到的上游 HTTP 错误响应执行透明透传。
Scenario: 非流式上游非 2xx 响应
- WHEN 非流式代理请求收到上游 HTTP 响应且状态码不是 2xx
- THEN SHALL 透传上游 status code
- THEN SHALL 透传过滤 hop-by-hop header 后的上游 headers
- THEN SHALL 透传上游 body
- THEN SHALL NOT 将上游错误包装为应用统一错误
- THEN SHALL NOT 将上游错误转换为客户端协议错误格式
Scenario: 流式上游非 2xx 响应
- WHEN 流式代理请求收到上游 HTTP 响应且状态码不是 2xx
- THEN SHALL 透传上游 status code
- THEN SHALL 透传过滤 hop-by-hop header 后的上游 headers
- THEN SHALL 透传上游 body
- THEN SHALL NOT 创建 StreamConverter
Requirement: 上游不可达错误
系统 SHALL 在没有收到上游 HTTP 响应时返回网关层错误。
Scenario: 上游连接失败
- WHEN ProviderClient 因 DNS、连接失败、TLS、超时或上下文取消等原因无法获得上游 HTTP 响应
- THEN SHALL 返回 HTTP 502 或合适的 5xx 状态码
- THEN SHALL 返回应用统一错误格式
- THEN code SHALL 为
UPSTREAM_UNAVAILABLE
Requirement: Hop-by-hop header 过滤
系统 SHALL 在透传上游错误响应时过滤 hop-by-hop headers。
Scenario: 过滤连接级 header
- WHEN 透传上游错误响应 headers
- THEN SHALL 过滤
Connection、Transfer-Encoding、Keep-Alive、Proxy-Authenticate、Proxy-Authorization、TE、Trailer、Upgrade - THEN SHALL 保留
Content-Type等普通响应 header
MODIFIED Requirements
Requirement: JSON 格式错误
系统 SHALL 对请求体 JSON 格式错误返回明确的错误信息。
Scenario: 请求体 JSON 格式错误
- WHEN 代理请求的请求体不是有效的 JSON 格式，且该接口需要网关解析请求体
- THEN SHALL 返回 HTTP 400 Bad Request
- THEN SHALL 返回以下 JSON 格式：
{ "error": "请求体 JSON 格式错误", "code": "INVALID_JSON" }
Scenario: Smart Passthrough 时请求体 JSON 格式错误
- WHEN 同协议 Smart Passthrough 场景下，请求体 JSON 格式不正确
- THEN SHALL 返回 HTTP 400 Bad Request
- THEN SHALL 返回以下 JSON 格式：
{ "error": "请求体 JSON 格式错误", "code": "INVALID_JSON" }