简介

本技术文档聚焦 DouPHP 小程序服务层的设计与实现，围绕 services 目录下的服务架构展开，重点说明 API 调用封装、数据处理逻辑、错误处理机制，以及各业务服务的职责划分（用户认证、商品、订单等）。同时解释服务间的依赖关系与调用方式，涵盖异步处理、请求拦截、响应格式化等关键主题，并提供服务层的扩展机制与自定义服务开发指南。

项目结构

本项目采用分层与模块化组织：

• api/service：面向小程序端对外暴露的 API 服务，包含支付、通用列表查询等能力。
• admin/service：面向后台管理的服务，负责小程序配置、导航、幻灯等管理能力。
• core/service：系统级基础服务（如定价、附件、日志、异常等），被上层服务复用。

graph TB
subgraph "API 服务"
A["WxPayService<br/>微信支付封装"]
B["MiniprogramCatalogQuery<br/>通用列表查询"]
end
subgraph "后台服务"
C["MiniprogramService<br/>小程序配置/包管理"]
D["MiniprogramNavService<br/>导航管理"]
E["MiniprogramShowService<br/>幻灯管理"]
end
subgraph "核心服务"
F["PricingService<br/>定价计算"]
G["Attachment/Url/DB<br/>基础设施"]
end
A --> G
B --> F
B --> G
C --> G
D --> C
E --> G

核心组件

• 微信支付封装服务：统一封装微信统一下单、签名、回调通知地址构建、XML 序列化/反序列化等能力，供小程序下单流程使用。
• 小程序通用列表查询服务：基于模块名动态查询数据，按分类、状态、排序、分页进行过滤，并输出小程序友好的 ViewModel。
• 小程序后台管理服务：负责小程序代码包管理、系统参数同步、配置更新与审计记录。
• 小程序导航服务：维护小程序顶部导航与底部 Tabbar，支持图标上传、排序、数量限制与配置同步。
• 小程序幻灯服务：维护小程序首页幻灯，支持图片上传、排序与删除清理。

架构总览

小程序服务层遵循“控制器薄、服务厚”的分层原则：

• API 层仅做参数校验与路由转发，具体业务由服务完成。
• 服务层通过核心基础设施（数据库、附件、URL、配置、定价）完成数据获取与转换。
• 后台服务提供对小程序运行态的配置管理能力，变更后触发配置同步。

sequenceDiagram
participant Client as "小程序客户端"
participant ApiCtrl as "API 控制器"
participant PaySvc as "WxPayService"
participant Wx as "微信支付接口"
participant Notify as "回调处理器"
Client->>ApiCtrl : "发起下单请求"
ApiCtrl->>PaySvc : "构造统一下单参数"
PaySvc->>Wx : "POST 统一下单"
Wx-->>PaySvc : "返回 prepay_id 等"
PaySvc-->>ApiCtrl : "组装支付参数"
ApiCtrl-->>Client : "返回支付参数"
Note over Client,Wx : "小程序唤起支付"
Wx-->>Notify : "支付结果回调"
Notify-->>ApiCtrl : "处理回调结果"

详细组件分析

微信支付服务（WxPayService）

• 职责：封装微信小程序支付的统一下单、签名生成、回调通知 URL 构建、XML 与数组互转、CURL 发送等。
• 关键流程：
  • 统一下单：组装参数（appid、mch_id、openid、out_trade_no、body、total_fee、spbill_create_ip、notify_url、trade_type=JSAPI），生成签名，提交至微信。
  • 回调通知：根据站点根路径或运行时请求信息构建 notify_url。
  • 支付参数：将 prepay_id 与时间戳、随机串、signType 等组合后返回给前端。
• 错误处理：CURL 异常抛出异常；XML 解析在 PHP 版本差异下做了兼容处理。
• 性能与安全：设置超时、SSL 校验、禁用实体加载（低版本）、避免明文密钥拼接泄露。

flowchart TD
Start(["开始"]) --> BuildParams["组装统一下单参数"]
BuildParams --> Sign["生成签名"]
Sign --> PostXml["POST XML 到微信"]
PostXml --> Resp{"是否成功"}
Resp --> |否| ThrowErr["抛出异常"]
Resp --> |是| BuildPay["构建支付参数"]
BuildPay --> Return["返回前端"]

小程序通用列表查询（MiniprogramCatalogQuery）

• 职责：为任意带 category_id/id/price 字段的模块表提供统一的列表查询，输出小程序友好视图模型。
• 数据处理：
  • 分类过滤：支持 ALL 与子分类树。
  • 状态过滤：product/article 默认只取已上架。
  • 排序与分页：支持外部传入 ORDER BY 片段与 limit。
  • 字段映射：价格格式化、销量占比、缩略图、详情页 URL、描述截取等。
  • 定价集成：调用定价服务计算优惠价。
• 复杂度：单次查询 O(N) 遍历组装，N 为返回条数；分类树查询取决于底层实现。

classDiagram
class MiniprogramCatalogQuery {
-pricingService : PricingService
+listing(module, catId, num, sort) array
}
class PricingService {
+salePrice(module, id, userId) array
}
MiniprogramCatalogQuery --> PricingService : "依赖"

小程序后台管理服务（MiniprogramService）

• 职责：小程序代码包管理、系统参数初始化与保存、配置同步、元数据解析。
• 关键能力：
  • 代码包目录准备与枚举。
  • 启用/删除代码包，并更新配置项。
  • 系统参数白名单持久化与同步。
  • 从 app.wxss 头部注释解析包元信息（名称、截图等）。
• 错误处理：非法操作直接返回或静默忽略；删除时触发云侧更新时间变更。

sequenceDiagram
participant Admin as "后台管理员"
participant Svc as "MiniprogramService"
participant Cloud as "Cloud"
participant DB as "数据库"
Admin->>Svc : "更新系统参数"
Svc->>DB : "写入参数"
Svc->>Cloud : "同步小程序配置"
Cloud-->>Svc : "确认"
Svc-->>Admin : "操作成功"

小程序导航服务（MiniprogramNavService）

• 职责：维护小程序顶部导航与底部 Tabbar，支持创建、编辑、删除、排序、图标上传与配置同步。
• 约束与校验：
  • Tabbar 数量上限校验（例如最多 5 个）。
  • type 必须为 miniprogram_top 或 miniprogram_tabbar。
• 业务流程：
  • 新增：解析 nav_menu，写入导航记录，上传图标，同步配置，记录审计日志。
  • 编辑：校验存在性，更新字段，可选替换图标，同步配置，记录审计日志。
  • 删除：二次确认后删除，清理资源，同步配置，记录审计日志。

sequenceDiagram
participant Admin as "后台管理员"
participant NavSvc as "MiniprogramNavService"
participant Model as "MiniprogramNav"
participant Attach as "附件存储"
participant Mpsvc as "MiniprogramService"
Admin->>NavSvc : "新增导航"
NavSvc->>Model : "创建记录"
NavSvc->>Attach : "上传图标"
NavSvc->>Mpsvc : "同步配置"
NavSvc-->>Admin : "返回 ID"

小程序幻灯服务（MiniprogramShowService）

• 职责：维护小程序首页幻灯，支持增删改查与图片上传、排序。
• 关键点：
  • 列表与编辑数据构建，图片 URL 转换。
  • 新增/编辑时上传并落盘。
  • 删除时清理图片并记录审计日志。

flowchart TD
Start(["开始"]) --> CreateOrUpdate{"新增/编辑?"}
CreateOrUpdate --> |新增| Store["写入记录"]
CreateOrUpdate --> |编辑| Update["更新记录"]
Store --> UploadImg{"是否上传图片?"}
Update --> UploadImg
UploadImg --> |是| SaveImg["保存附件"]
UploadImg --> |否| Sync["跳过"]
SaveImg --> End(["结束"])
Sync --> End

依赖关系分析

• 服务间耦合：
  • MiniprogramNavService 依赖 MiniprogramService 以同步配置。
  • MiniprogramCatalogQuery 依赖 PricingService 计算优惠价。
  • 所有服务均依赖核心基础设施（DB、Attachment、Url、Config、Storage）。
• 外部依赖：
  • 微信支付 API（统一下单、回调）。
  • 云配置服务（用于小程序配置文件的变更与更新）。

graph LR
Nav["MiniprogramNavService"] --> Mpsvc["MiniprogramService"]
Catalog["MiniprogramCatalogQuery"] --> Pricing["PricingService"]
Show["MiniprogramShowService"] --> Storage["Storage/Attachment"]
Pay["WxPayService"] --> WxAPI["微信支付API"]
Mpsvc --> Cloud["Cloud 配置服务"]

性能考量

• 数据库查询：
  • 列表查询建议合理设置 limit 与索引（category_id、status、created_at）。
  • 分类树查询应避免重复计算，必要时缓存。
• 网络 I/O：
  • 微信支付请求设置合理的超时与重试策略。
  • 回调处理需幂等，防止重复入账。
• 文件存储：
  • 图片上传建议使用对象存储与 CDN，减少服务器压力。
• 内存与 CPU：
  • 列表组装阶段避免大对象循环，按需裁剪字段。

故障排查指南

• 微信支付失败：
  • 检查统一下单参数完整性与签名是否正确。
  • 核对 notify_url 可访问性与域名配置。
  • 查看 CURL 错误码与日志定位网络问题。
• 列表为空或数据异常：
  • 检查分类过滤条件与 status 过滤。
  • 验证排序片段与 limit 参数。
  • 确认定价服务返回格式是否符合预期。
• 导航/幻灯无法生效：
  • 确认配置同步是否成功。
  • 检查图标上传是否成功且路径正确。
  • 查看审计日志定位操作来源。

结论

DouPHP 小程序服务层通过清晰的分层与职责划分，实现了支付、列表查询、后台管理等核心能力。服务之间依赖明确，借助核心基础设施保证了可扩展性与可维护性。结合统一的错误处理与审计机制，便于问题定位与运维保障。后续可在现有基础上引入缓存、队列与更完善的监控指标，进一步提升性能与稳定性。

附录：扩展与自定义服务开发指南

• 新增服务步骤：
  • 在对应目录（api/service 或 admin/service）创建服务类，继承 BaseService。
  • 通过构造函数注入所需依赖（如 PricingService、Cloud、Storage 等）。
  • 实现方法时遵循单一职责，保持输入输出契约稳定。
  • 如需对外暴露 API，在控制器中调用服务并返回统一响应格式。
• 请求拦截与响应格式化：
  • 建议在中间件层完成鉴权、限流、安全头设置等横切关注点。
  • 在服务层统一处理业务异常，并在控制器层转换为标准响应体。
• 异步处理：
  • 对于耗时任务（如邮件、统计、第三方回调处理）建议使用队列或异步任务。
  • 确保回调幂等与重试策略。
• 自定义服务示例要点：
  • 参考 MiniprogramCatalogQuery 的数据组装模式，输出稳定的 ViewModel。
  • 参考 MiniprogramService 的参数白名单与配置同步模式，保证安全性与一致性。
  • 参考 MiniprogramNavService 的表单校验与审计日志记录，提升可追溯性。