HTTP 契约:超时、状态码与连接复用的边界
用真实本地 HTTP 往返理解认证、错误响应、版本路径和连接生命周期,区分请求失败与业务是否执行。
调用模型接口并不是“传一个字符串,收一个字符串”。一次请求至少包括方法、目标路径、请求头和可选请求体;响应包括状态码、响应头与响应体。认证、媒体类型、超时、重试、连接池与业务幂等共同决定失败后系统是否还能正确恢复。
先分开传输状态与业务结果
2xx 表示服务器按相应方法语义成功处理请求,但响应字段是否符合应用约束仍要验证。400 通常指请求有问题;401 表示缺少有效认证并配合认证挑战,403 表示服务器拒绝执行;404 不必揭示资源是否对其他身份存在。429 要关注限流策略和 Retry-After,5xx 说明服务端链路出了问题,却不能证明业务动作从未执行。
稳定错误契约可以包含 error.code、可展示消息、request_id 和必要重试信息。客户端应按机器错误码分支,而不是匹配英文报错文本。错误正文也可能不是 JSON,例如网关返回 HTML;先看状态与 Content-Type,再做受限解析,避免原始代理页面被当成模型输出。
API版本应同时覆盖路径/请求字段/响应字段/错误语义。兼容接口路径相同,不保证流式事件、工具参数和模型角色完全一致。升级应通过固定契约样本与真实小请求验证,不只确认 HTTP 200。
超时并不是一个数字
连接超时通常覆盖建立连接所需时间,具体客户端对 DNS、代理和TLS阶段的计入方式可能不同。读取超时限制等待响应数据的间隔或阶段,写入超时限制发送过程,连接池等待超时限制拿到可用连接前的等待。总截止时间则约束整次业务操作,包括排队和重试;仅给每次读取设两秒,不保证整个流式响应两秒结束。
读取超时时,请求可能已经被服务器完整接收甚至执行。对扣款、发邮件、创建工单等动作,应使用幂等键和结果查询/对账,而不是立即重试。即使连接超时,也应结合代理、客户端阶段定义和实际发送情况分析,不能把异常类型直接等同于“绝对没执行”。
跑真实本地请求与连接复用
保存为 http_contract.py,运行 python -X utf8 http_contract.py。程序仅监听127.0.0.1的临时端口,启动本地服务后自动发送三次GET,再关闭客户端与服务器。固定Bearer值只用于教学,不是生产凭据。
"""真实 localhost HTTP 请求;不调用外部模型,认证令牌为固定教学值。"""
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from http.client import HTTPConnection
from threading import Thread
import json
class Handler(BaseHTTPRequestHandler):
protocol_version = 'HTTP/1.1'
def log_message(self, *args):
pass
def do_GET(self):
if self.headers.get('Authorization') != 'Bearer local-demo':
status, payload = 401, {'error': {'code': 'unauthenticated'}}
elif self.path == '/v1/status':
status, payload = 200, {'status': 'ready'}
else:
status, payload = 404, {'error': {'code': 'not_found'}}
data = json.dumps(payload).encode()
self.send_response(status)
self.send_header('Content-Type', 'application/json')
self.send_header('Content-Length', str(len(data)))
if status == 401:
self.send_header('WWW-Authenticate', 'Bearer')
self.end_headers()
self.wfile.write(data)
def run():
server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)
thread = Thread(target=server.serve_forever, daemon=True)
thread.start()
connection = HTTPConnection(*server.server_address, timeout=2)
results = []
try:
for path, token in [('/v1/status', ''), ('/v1/status', 'local-demo'), ('/v1/missing', 'local-demo')]:
connection.request('GET', path, headers={'Authorization': 'Bearer ' + token})
response = connection.getresponse()
# 消费完整响应体后才复用连接。
payload = json.loads(response.read())
results.append((response.status, payload))
finally:
connection.close()
server.shutdown()
server.server_close()
thread.join()
return results
if __name__ == '__main__':
for status, payload in run():
print(status, json.dumps(payload, sort_keys=True))401 {"error": {"code": "unauthenticated"}}
200 {"status": "ready"}
404 {"error": {"code": "not_found"}}客户端用同一个 HTTPConnection 顺序发送请求,每次完整读取响应体后再复用。服务端给出 Content-Length,让持续连接上能明确识别消息边界。真实连接池需要限制每目标/总连接数、处理过期连接和关闭;为每次请求新建客户端会失去复用,池过小则可能让大量任务卡在池等待而非模型执行。
这个实验验证本地HTTP往返、认证分支和错误契约,没有验证TLS、代理、远端限流或模型能力。若要实验超时,应给服务端明确延迟并记录阶段,不用一次偶然网络故障推导普遍结论。
认证与日志应在哪里处理
认证头由受信配置构造,不让模型任意指定目标URL和凭据。跨主机重定向时是否转发 Authorization 必须受控,避免凭据被带到非预期主机。服务端认证成功后仍需检查资源授权;“知道token”与“有权操作这个文档”不是同一个判断。
记录 request_id、提供方请求ID、状态、阶段耗时、重试次数与响应大小,通常比记录完整prompt更利于定位且更少暴露数据。日志中的Authorization必须脱敏;调试期间临时打开原始请求日志,也需要明确范围和清理策略。
并发提高后若错误突然增加,先区分池等待、DNS/连接失败、服务端限流、读取超时和响应校验失败。对所有失败统一增加重试,会增加上游压力并隐藏根因。将时间预算、幂等性和分类错误作为调用层的显式接口,后续Agent工具才能可靠地决定恢复方式。
逐项情境追问与故障定位
以下为机制分析与手算情境。可先遮住回答独立判断,再核对输入、失败位置和选择条件;它们不代表真实模型、远端服务或设备实验记录。
请求响应:HTTP200返回HTML,能当模型文本继续处理吗?
先核Content-Type和受限响应体,再按预期结构验证。200只说明相应HTTP语义成功,网关登录页并非模型响应。容错解析可兼容少量提供方差异,但不可把任意正文接受为成功;记录request_id、类型与大小,定位网关还是客户端契约失配。
状态码:401、403、429都重试三次有什么问题?
401检查凭据有效性,403检查授权策略,429按配额与Retry-After在预算内退避。重试短暂限流可能恢复,反复重试权限错误只放大负载。分别固定三种响应确认分支,不能靠英文消息包含“error”决定策略。
认证:自己的token读到了另一个租户文档,认证为何没防住?
认证确认身份,授权必须把可信身份与资源租户绑定;模型传入tenant_id不能成为授权依据。服务端派生租户更可靠,但跨租户管理员操作要额外显式策略。保留主体/资源/决策日志,换两个身份访问同一资源复测,切勿记录完整token。
连接池:并发从10升到100后大量超时,模型却空闲,怎么查?
区分池等待与上游读取耗时,检查响应体是否耗尽/关闭以及每目标连接上限。连接复用减少握手,过小池会排队,盲目扩池又可能压垮上游。比较等待许可、取连接、发送、首字节时间,先修泄漏再按容量调池。
超时:读取超时后重发创建工单,生成了两张,如何恢复?
超时只说明客户端没及时读到结果,服务端可能已经提交。使用稳定幂等键并查询结果/对账,再决定重试。更长读取超时降低误判却占用资源,总截止时间还要覆盖排队和重试;检查服务端request_id对应提交记录,不能直接假定没执行。
API 版本与错误契约:升级后响应仍200,客户端却无法识别错误码,如何回归?
版本契约包含字段类型、错误码和事件顺序,不止URL。保存旧/新固定成功与失败样本,逐条验证解析和恢复分支。新增可选字段通常较兼容,改名或改错误语义需迁移/版本化;先定位服务器输出与客户端schema哪边漂移。
课后练习展开习题收起习题
先独立作答,再展开参考思路。检查自己的解释是否包含机制、条件和反例。
HTTP200是否表示模型结果可直接写库?
参考思路与常见误区
不表示。仍需检查媒体类型、JSON结构、字段类型、业务语义与权限。网关和供应商错误响应也可能有不同格式,传输状态与业务结果应分别建模。
常见误区:只判断status==200就信任全部响应字段。
读取超时后能否立即重发有副作用的POST?
参考思路与常见误区
请求可能已执行,只是响应未到。应依据幂等键、服务端去重约定和结果查询/对账策略恢复,不能由超时直接推断未执行。连接超时也需结合阶段与代理行为分析。
常见误区:把客户端没收到结果等同服务端没执行。
每次读取超时两秒,是否整个流式请求最多两秒?
参考思路与常见误区
不一定。读取超时常限制等待数据间隔或阶段,持续收到数据可让总时长很长。总截止时间需包含队列、连接、读写和重试,并检查客户端的具体语义。
常见误区:只设置一个timeout数字就承诺端到端时限。
连接池等待与模型推理慢怎么区分?
参考思路与常见误区
分别记录排队/取连接、建连、发送、首响应与完成时间。池等待可能来自池容量不足或响应未释放;不能把发送前等待全部算进模型推理,也不宜盲目增加重试。
常见误区:只测请求总时长就认定模型算得慢。
401和403如何区分?凭据日志该怎样处理?
参考思路与常见误区
401表示缺少有效认证并按协议给出挑战,403表示服务拒绝执行。认证成功仍要资源授权。日志记录关联ID与错误分类,Authorization脱敏,重定向跨主机也要控制凭据转发。
常见误区:把认证通过等同拥有任意资源权限。
语义依据 RFC 9110,本地调用实现参考 http.client。