new_sdk_wu/md_go_migration_api/00-api-go-migration-index.md

api 模块 Go 重构梳理索引

生成时间：2026-06-09

源代码范围：C:\web\composer\qi_meng\new_sdk\www\new_sdk\application\api

目标用途：为后续将当前 PHP/ThinkPHP SDK API 重构为 Go 服务提供业务逻辑、接口边界、数据依赖和迁移顺序参考。

文档清单

1. 01-api-architecture-and-business-domains.md
   • 当前 api 模块的入口协议、公共基类逻辑、业务域拆分。
2. 02-controller-endpoint-inventory.md
   • 控制器、服务类、渠道适配器清单，便于迁移时逐个勾兑。
3. 03-core-business-flows.md
   • 登录注册、支付下单、支付回调、聚合渠道、实名防沉迷、MLBB 活动等核心流程。
4. 04-data-dependencies-and-risks.md
   • 数据表、Redis key、外部 SDK/支付渠道、敏感配置和迁移风险。
5. 05-go-refactor-blueprint.md
   • Go 分层结构、接口抽象、迁移阶段和测试策略。
6. 11-observability-stack-guide.md
   • Prometheus、Grafana、Loki、Tempo、OpenTelemetry、Alloy 的用途说明和第一版落地建议。
7. 12-development-roadmap-todo.md
   • GoFrame 重构 5 个版本的开发计划 TODO，包括底座、账户、SDK 协议、支付订单、渠道运营。

当前判断

当前项目不是单纯的 API CRUD 服务，而是一个游戏 SDK 中台：

• 客户端请求统一经过 AES 解密、MD5 签名、App 配置校验、Token/IMEI 校验。
• 账号体系同时承载主账号、子账号、游戏归属渠道、实名状态、设备信息。
• 支付链路是最大复杂度来源，包含游戏充值、平台币充值、专属币、代金券、混合支付、第三方支付参数生成、支付异步通知、CP 发货通知。
• complex 是聚合/联运渠道适配层，约 50 多个渠道类，接口形式相似但细节差异很大。
• v2 已经在重构部分业务，例如用户中心、订单、平台币、代金券、聚合渠道处理，Go 迁移时应优先吸收这些较新的边界。
• api/config.php 和部分服务代码里混有渠道密钥、证书、回调地址等敏感配置，Go 版本不要照搬到代码仓库，应移入环境变量、密钥管理或配置中心。

建议迁移路线

建议使用 strangler pattern 渐进迁移，不建议一次性重写全部接口：

1. 先迁移公共协议层：AES、签名、App 校验、Token 校验、响应加密。
2. 再迁移低风险读取类接口：版本配置、公告、游戏包信息、礼包列表、订单查询。
3. 然后迁移账号安全类接口：登录、注册、短信、设备、实名，保留 PHP 旁路比对。
4. 支付下单和支付回调最后迁移，必须先补齐 golden case、幂等、金额校验和事务测试。
5. complex 渠道适配器单独做 Go 插件式注册表，按渠道逐个迁移，不要重新堆成一个大控制器。

迁移时必须保留的兼容点

• 客户端密文协议：默认 AES-128-ECB，debug 请求可明文。
• 签名算法：过滤 sign，按 key 升序拼接 key=value，追加 client_appkey，小写后 MD5。
• Token 格式：userid|username|gameid|sub_username|token_random|sdk 经 auth_code 加密。
• Redis 登录态：token => imeil，token|sdk|userid|gameid => token_random。
• 响应结构：code/msg/time/data/err_code，生产环境需要加密输出。
• 支付订单状态：cy_pay.status、cy_paycpinfo.payflag、member_coin_pay.status 的历史语义不能改。
• CP 回调签名字段和成功判定：当前多数逻辑以 CP 返回字符串 success 为成功。

迁移优先级概览

优先级	模块	理由
P0	协议层、认证层、配置层	所有接口共享，错了会全量不可用
P0	支付订单与回调状态机	涉及资金、发货、幂等、退款
P1	登录注册、子账号、实名防沉迷	用户入口，强依赖历史数据兼容
P1	complex 渠道适配	渠道多，适合抽象接口后逐个迁移
P2	订单/礼包/代金券/平台币查询	可先灰度，风险相对可控
P2	MLBB 活动、第三方数据 API	活动/渠道专项，可按需求迁移