用途:在 Ruby/Rails 项目中对接外部 API、编写 HTTP 客户端、从外部服务构建数据管道或新增 API 消费者时使用。
主要能力:提供 Auth(OAuth/token 管理与缓存)、Client(HTTP 请求、响应解析、错误包装)、Fetcher(查询编排、轮询、分页)、Builder(响应转为结构化数据)、Domain Entity(领域配置与查询定义)五层模式,并给出新增领域实体的步骤与接入检查清单。
使用方式:遵循 ruby-service-objects 的共享约定(YARD 文档、常量、响应格式、app/services/ 目录)。硬性门禁要求每层测试先于实现:先用 instance_double 或哈希工厂写 spec,运行确认因层不存在而失败,再写实现,按 Auth→Client→Fetcher→Builder→Entity 顺序逐层重复。Client 提供 self.default、Error 类与错误包装;Builder 按 ATTRIBUTES 白名单过滤字段;实体类通过 .fetcher 装配层,并用 sanitize_sql 处理查询参数。凭证来自加密配置而非硬编码。
适用场景:OAuth 接入、需要轮询/重试/分页的外部数据拉取、需要把外部响应映射为领域对象并隐藏内部结构的集成。
限制与风险提示:资料要求 HTTP 调用必须配置超时,错误需包装,避免暴露完整 API 响应,缺少错误场景测试(网络失败、无效 JSON、4xx/5xx)以及分页支持属危险信号;凭证提交到 git 属红线。未提供具体安装命令、版本要求与完整代码,暂未提供。