Download the PHP package internal-services/service-sdk without Composer

Internal Service SDK

供各国家 PHP 业务项目复用的内部 HTTP 客户端，兼容 PHP 7.4。当前包含：

• 固定九行 Canonical Request 的 X-Internal-* HMAC-SHA256 签名；
• data-mid 事件类型、稳定事件 ID、事件工厂、订单上下文脱敏、批量结果及高阶上报门面；
• data-mid 单事件和批量事件 HTTP 上报；
• service-notification FCM 设备注册；
• toolbox-service 飞书 V2 告警、告警目录及旧自定义消息兜底；
• AJ 设备与事件 DTO、JSON 客户端及可配置重试；
• 支持服务身份与 Toolbox Actor/Scopes 的原始 Signed HTTP 请求；
• 可替换的 TransportInterface，以及可选 Swoole、Guzzle Transport。

包不读取环境变量、不访问 Redis 或数据库。调用方负责注入具体调度器、去重存储、告警 ID、业务 Payload 与运行配置； SDK 统一调度/去重接口、上报生命周期和协议客户端。Secret 不得写入仓库或日志。

安装

包发布在 Packagist，可直接安装：

无需配置 Composer VCS Repository、GitHub Token 或 SSH Deploy Key。

data-mid

EventFactory 统一生成协议字段、事件时间、稳定 event_id 和生产端去重 Key；EventType、EventId、 OrderContext 也可独立使用。reportEvent() 和 reportBatch() 返回 HttpResponse。需要推进批处理断点时使用 reportBatchResult()，只有 BatchReportResult::isComplete($expected) 为 true 才表示全部接收。

data-mid 事件字典中的日期时间字段在线上 Payload 中统一为 JSON 整数 Unix 秒时间戳。命名工厂会把可选数组中 纯数字形式的秒时间戳规范为整数，并拒绝无时区/带 Offset 日期字符串、浮点数和毫秒时间戳； user.overdue.daily.batch_date 只是国家当地业务日期，继续使用 YYYY-MM-DD。

推荐业务入口使用 DataMidReporter：它统一命名事件、异步派发、生产端去重租约、失败释放和批量完整接收判断。 单事件遇到 data-mid 重启窗口常见的 502/503/504 时，默认按约 1 秒、3 秒、7 秒（各带 20% 抖动）有限重试； 同一次事件保持稳定 event_id，每次 HTTP 请求重新生成 HMAC Nonce 和签名。其他状态、低层 reportEvent() 与 批量接口不自动重试。该能力只覆盖短暂网关不可用，调用方进程退出或长时间故障仍需未来 Outbox 才能保证不丢失。

已有用户登录、历史接入或迁移补偿使用 userAssetSynced() 校准中台资产，不得补发 user.registered。其中 app_id 始终是规则与统计使用的业务逻辑 App，实际安装包通过 package_app_id 传递，供设备和短链路由使用。 source_updated_at、可选的 registered_at 与 last_active_at 必须是 Unix 秒时间戳； 国家项目用 CallableDispatcher 适配协程，以 DedupStoreInterface 适配 Redis；SDK 自身不依赖具体框架或缓存实现。 可通过 DataMidReporter 选项 transient_retry_delays_ms 覆盖等待序列，传空数组可关闭；测试可注入 Sleeper 与 Jitter，生产默认使用毫秒 usleep，在已启用协程 Hook 的 Hyperf 调用方中不会阻塞业务请求线程。

内部管理端请求

Toolbox/BFF 调用 data-mid、service-notification 或 service-short-link 管理端时，使用 SignedHttpClient 对实际发送的 Method、Path + Query 和原始 Body 字节签名，并通过 InternalRequestContext 传递已经由 Toolbox 鉴权的操作人和权限。SDK 不读取 Laravel Request、用户模型或 权限数据，也不会自行授予 Scope。

Idempotency-Key 等不属于九行 Canonical 的协议 Header 可以通过第五个参数传入； X-Internal-* 和 X-Request-Id 禁止从附加 Header 覆盖。

通知设备注册

DeviceRegistration 在发出请求前统一规范国家、平台和可选 AAID，并校验通知服务的完整字段、长度和 RFC 3339 时间契约。原有 register($installUuid, $payload) 作为低层兼容入口继续保留。

toolbox 飞书告警

toolbox 返回 code=0 表示已发送，code=200 表示规则判定后跳过，两者都属于正常受理。V2 调用失败时， FeishuNotifier 可自动调用旧自定义消息接口兜底，且不会把原始业务 Payload 复制到兜底内容。

AJ 事件客户端

AjClient 统一 /api/device/ma 与 /api/event 的 JSON 请求、超时、响应解析和有限重试；协程项目可注入非阻塞 Sleeper。AjEvent 强制调用方显式传入 clientVersion，避免复制国家代码时沿用错误值。订单状态映射、首复贷、 风控判断、SQL、Redis 业务幂等和延迟任务仍属于业务项目。

请求上下文与测试

构造函数支持注入 Transport、时钟、Nonce 和 Request ID Resolver。Hyperf 项目可用 Resolver 传递当前请求 ID； 单元测试使用 Fake Transport 验证完整方法、URL、正文和签名，不需要启动公共服务。

ext-swoole 与 guzzlehttp/guzzle 均为按运行时选择的可选依赖：原有 Hyperf/Swoole 项目可以继续使用默认 SwooleHttpTransport；Laravel 等项目显式注入 GuzzleHttpTransport，安装 SDK 不再强制要求 Swoole 扩展。