SuperAPI AI 工具集

bep-http-engineering

编程与开发

查看项目

更新于 11-06 21:01

技能介绍

用途

bep-http-engineering 是一套 HTTP 工程约束规则,用于在任务明显影响 HTTP 请求生命周期或协议行为时,指导设计、实现或评审相关语义。它声明自身负责跨越前后端边界的共享语义;运行时结构由前端工程与后端工程技能负责,REST/OpenAPI 资源与表示设计由专门的 OpenAPI 设计技能负责。

主要能力

该技能以条目形式给出八组约束:

  1. 端到端追踪完整请求生命周期,包括调用方请求、客户端校验与请求构造、认证与服务器端授权、领域操作与持久化、响应或异步结果、调用方对账与重试及可见失败;并要求覆盖成功、校验失败、认证、授权、冲突、超时、取消、重复、结果不确定与意外失败等适用情形,每个状态都有负责人和稳定的协议语义。
  2. 一次性定义完整 HTTP 契约,包括方法与规范路径、各类输入、成功与错误表示、状态码与稳定错误标识、认证授权预期、缓存与新鲜度及失效、幂等并发重试取消超时语义、关联与 Trace 传播、兼容与迁移行为。要求在服务器传输层校验不可信输入,仅在传输边界将领域与应用失败转换为 HTTP,并保持已发布消费者的兼容性。
  3. 将身份与权限分离:在 HTTP 执行边界完成认证并产出规范化不可变主体,再针对具体资源、操作、归属、租户、状态与字段单独授权;不把原始令牌与提供方声明带入业务代码。
  4. 让写入在重复与并发下安全:为刷新、重复提交、超时、客户端重试、并发更新与未知响应结果定义行为,使用幂等标识、条件请求、版本检查或数据存储约束;仅在拥有完整操作语义的边界重试瞬态失败,并要求幂等、有限次数、退避、抖动与总体截止时间。
  5. 集中管理协议策略:在框架原生请求与响应边界处理校验与输入规范化、稳定错误映射、认证提取、请求与 Trace 关联、安全响应头、通用序列化与内容协商、访问事件可观测性及审计派生;处理器只负责操作特定转换,业务模块不依赖 HTTP 状态码、头、请求响应对象与提供方认证类型。
  6. 保护每一次 HTTP 信任转换:凭证与特权数据不得进入 URL、重定向、普通日志、错误体、缓存与浏览器可读配置;应用平台既有的 Cookie 范围、传输安全、CSRF、CORS 或来源策略、重定向、上传与内容处理控制;按资源与字段授权,而非仅按路由或粗粒度角色;对不可信输入施加大小、解码后大小、内容、速率与成本限制;使用成熟协议与密码学实现,不自行发明认证或令牌格式。
  7. 关联完整交互:将稳定的请求与 Trace 上下文从调用方贯穿 HTTP 边界、下游依赖与异步工作;按支持的规范提取传入 Trace 上下文,仅在无有效父级或调度语义需要时新建根;由服务器请求边界拥有唯一结构化诊断完成事件,指标用于聚合、追踪用于因果流,且不记录请求或响应体。
  8. 应用 HTTP 完成门禁:当生命周期阶段或结果缺少明确负责人或语义、契约行为隐式或矛盾、将客户端校验当作服务端校验、将认证当作授权、重复或不确定写入可能静默重复不可逆工作、HTTP 类型渗入业务策略、协议策略散落在各处理器、凭证或敏感体可能进入 URL 日志缓存错误、请求与下游及异步工作无法关联,或适用的 REST/OpenAPI 或已加载验证门禁未满足时,拒绝完成。

使用方式

该技能以约束清单和完成标准的形式应用:在相关任务中逐项对照上述规则,按生命周期阶段梳理归属与语义,并依据完成门禁判断实现是否可视为完成。对于 REST 路由或 OpenAPI 契约,若相应的 OpenAPI 设计技能可用则加载并由其负责资源建模;若不可用,应将专门资源建模门禁明确标记为未满足。

适用场景

适用于涉及 HTTP 请求生命周期或协议行为的开发任务,例如认证传输、缓存、幂等、并发、重试、上传、重定向等语义的设计、实现与评审。

限制

资料未提供该技能的安装方式、具体平台支持、收费与价格信息,暂未提供;亦未提供示例代码或命令。