简介
本技术文档围绕 DouPHP 小程序的组件复用机制展开，重点说明：
- 组件继承模式：基类设计、子类扩展、方法重写在小程序中的落地方式与最佳实践。
- 组合模式：通过组件嵌套、动态组装与条件渲染实现复杂 UI 的组合式复用。
- 插件机制：基于生命周期钩子与全局入口的扩展点注入（以 HTTP 拦截器、全局 Store 引导为例）。
- 配置化复用：主题切换、样式定制、行为配置等可插拔能力。
- 版本管理与兼容性：多环境/多主题下的差异处理与升级策略。
- 实战示例：结合 navbar 组件与 App 启动流程，展示不同复用模式的实现路径与适用场景。
项目结构
DouPHP 小程序采用“默认模板 + 公司定制”的双套结构，便于在不同业务线之间共享基础能力并差异化定制：
- miniprogram/default：通用默认实现，包含公共组件、服务、工具与页面骨架。
- miniprogram/company：公司级定制实现，覆盖默认实现的关键部分，提供差异化行为与样式。
- 组件位于各自 components 目录下，如 navbar 组件在两套结构中均存在，便于按主题/业务替换。
- 应用入口 app.ts 负责全局初始化、错误处理、自动更新、推广参数解析等，体现插件式扩展点。
graph TB
subgraph "小程序"
A["default/app.ts"] --> B["company/app.ts"]
C["default/components/navbar"] --> D["company/components/navbar"]
E["default/services/http.js"] -.-> F["company/services/http.js"]
end
G["页面/业务模块"] --> C
G --> D
H["全局Store/状态管理"] --> A
H --> B核心组件
- 导航栏组件（navbar）：提供标题、背景色、标题色、滚动透明度、返回/首页跳转、调试入口等能力；支持自定义插槽，便于嵌入菜单或操作按钮。
- 应用入口（App）：统一注册 HTTP 错误拦截、全局 Store 引导、推广参数解析、自动更新、全局异常捕获与调试开关。
这些组件体现了：
- 配置化复用：通过 properties 暴露可配置项，页面按需传入。
- 组合模式：页面将 navbar 与其他业务组件组合，形成完整视图。
- 插件机制：App 层通过拦截器与 Store 引导完成横切关注点的注入。
架构总览
下图展示了小程序启动到页面渲染过程中，组件复用与插件机制的协作关系。
sequenceDiagram
participant WX as "微信运行时"
participant APP as "App(入口)"
participant HTTP as "HTTP服务/拦截器"
participant STORE as "全局Store"
participant PAGE as "页面"
participant NAV as "Navbar组件"
WX->>APP : 启动 onLaunch
APP->>HTTP : 注册 onError 拦截
APP->>STORE : bootstrapStores() 初始化
APP->>APP : 解析推广参数 user_sn
APP->>WX : 计算导航栏高度/窗口信息
APP->>WX : 检查更新/开启调试
WX->>PAGE : 加载页面
PAGE->>NAV : 使用 <navbar> 并传入 title/url/showMenu 等
NAV-->>PAGE : 事件回调 goBack/goHome/openDebug详细组件分析
组件继承模式（小程序视角）
小程序原生不支持传统类的继承，但可通过以下模式实现“继承式复用”：
- 基类封装：将通用逻辑抽离为独立模块（如 utils、services），由多个组件/页面复用。
- 子类扩展：在特定组件中引入基类能力，并通过 properties/methods 扩展自身特性。
- 方法重写：在子类中覆盖父级行为（例如在 company 版本的 navbar 中调整属性观察者逻辑）。
在本项目中，navbar 组件在 default 与 company 两套实现中分别定义，体现了“同构替换”的继承思想：
- 默认实现提供基础能力。
- 公司实现可在不改动页面的前提下，替换行为与样式，达到“继承+重写”的效果。
classDiagram
class NavbarDefault {
+properties : title, backgroundColor, titleColor, url, showMenu
+data : statusBarHeight, navigationBarHeight, ...
+methods : goBack(), goHome(), openDebug()
}
class NavbarCompany {
+properties : title, backgroundColor, titleColor, url, showMenu
+data : statusBarHeight, navigationBarHeight, ...
+methods : goBack(), goHome(), openDebug()
}
class AppEntry {
+onLaunch()
+onShow()
+onError()
+parsePromotionFromLaunchOptions()
+autoUpdate()
}
NavbarDefault <|-- NavbarCompany : "同构替换(继承式复用)"
AppEntry --> NavbarDefault : "页面组合使用"
AppEntry --> NavbarCompany : "页面组合使用"组合模式的应用
- 组件嵌套：页面通过 WXML 将 navbar 与其他业务组件组合，形成完整界面。
- 动态组装：通过 properties 动态传入 title、url、showMenu 等，控制组件呈现。
- 条件渲染：根据数据或环境（如调试开关）决定是否显示调试入口圆点。
flowchart TD
Start(["页面渲染"]) --> LoadNav["加载 navbar 组件"]
LoadNav --> BindProps["绑定 properties<br/>title/url/showMenu/backgroundColor/titleColor"]
BindProps --> RenderUI{"是否启用调试?"}
RenderUI --> |是| ShowDot["渲染调试入口圆点"]
RenderUI --> |否| HideDot["隐藏调试入口圆点"]
ShowDot --> UserAction["用户交互: 返回/首页/调试"]
HideDot --> UserAction
UserAction --> HandleEvent["触发 goBack/goHome/openDebug"]
HandleEvent --> End(["完成"])插件机制的设计原理
- 插件注册：App 启动时注册 HTTP 错误拦截器，集中处理 UNAUTHORIZED 等错误，触发登出流程。
- 生命周期钩子：利用 onLaunch/onShow 进行推广参数解析、全局 Store 初始化、设备信息计算、自动更新检查。
- 扩展点注入：通过 services/http.js 的 onError 回调注入业务逻辑；通过 stores/index.js 的 bootstrapStores 注入全局状态。
sequenceDiagram
participant WX as "微信运行时"
participant APP as "App(入口)"
participant HTTP as "HTTP拦截器"
participant AUTH as "AuthStore"
WX->>APP : onLaunch(options)
APP->>HTTP : onError(handler)
APP->>APP : parsePromotionFromLaunchOptions()
APP->>APP : bootstrapStores()
HTTP-->>APP : 错误回调(UNAUTHORIZED)
APP->>AUTH : logout()组件的配置化复用
- 主题切换：通过 properties 传入 backgroundColor/titleColor，实现不同主题的导航栏外观。
- 样式定制：结合 WXML/WXSS 与 properties，实现标题、背景、透明度的灵活配置。
- 行为配置：通过 url 指定返回目标，showMenu 控制菜单显示，openDebug 控制调试入口可见性。
组件版本管理与兼容性处理
- 双套实现：default 与 company 两套 navbar 与 app 实现，便于按业务线/主题切换。
- 环境门控：通过 isDebugEnv/isServerDebug 控制调试功能，避免生产环境泄露。
- 兼容处理：对 scene/query 等多来源推广参数进行兼容解析，确保不同打开方式下均可正确获取 user_sn。
- 自动更新：使用 getUpdateManager 检测并提示更新，保证客户端版本一致性。
依赖关系分析
- App 依赖：
- services/http.js：提供网络请求与错误拦截。
- stores/index.js：引导全局状态，实现秒开与刷新。
- utils/env.js：判断运行环境与调试开关。
- utils/promotion.js：写入推广参数。
- config/site.js：站点配置（root_url/mp_url/douLoading）。
- Navbar 组件依赖：
- utils/env.js：环境判断。
- utils/ui.js：页面跳转封装。
- 微信小程序 API：navigateBack/switchTab/navigateTo。
graph LR
APP["App(入口)"] --> HTTP["services/http.js"]
APP --> STORE["stores/index.js"]
APP --> ENV["utils/env.js"]
APP --> PROMO["utils/promotion.js"]
APP --> SITE["config/site.js"]
NAV["navbar 组件"] --> ENV
NAV --> UI["utils/ui.js"]
NAV --> WXAPI["wx.* API"]性能考量
- 启动优化：onLaunch 中尽早执行关键初始化（HTTP 拦截、Store 引导），减少首屏等待。
- 渲染优化：navbar 使用 multipleSlots 提升布局灵活性，减少重复渲染。
- 调试开关：仅在非正式版与服务端调试开启时显示调试入口，降低生产开销。
- 更新策略：使用 getUpdateManager 异步检查更新，避免阻塞启动。
故障排查指南
- 未授权错误：HTTP 拦截器捕获 UNAUTHORIZED 后调用 authStore.logout()，需检查登录态与接口鉴权。
- 页面不存在：onPageNotFound 记录 path，便于定位路由拼写问题。
- 推广参数丢失：检查 scene/query 解析逻辑，确认 user_sn 是否正确写入 storage。
- 调试入口不显示：确认 isDebugEnv/isServerDebug 双门控条件，避免误显或隐藏。
结论
DouPHP 小程序通过“默认+定制”的双套结构与组件化设计，实现了高内聚、低耦合的复用体系：
- 继承模式：通过同构替换实现“基类+子类”的扩展与重写。
- 组合模式：通过 properties 与插槽实现灵活的组件嵌套与条件渲染。
- 插件机制：通过 App 生命周期与 HTTP 拦截器完成横切能力的注入。
- 配置化复用：通过主题与行为配置满足多业务线需求。
- 版本与兼容：通过环境门控与自动更新保障稳定性与一致性。
附录
- 组件声明文件：navbar.json 用于声明组件类型，确保框架正确识别。
- 多套实现：default 与 company 两套 app.ts 与 navbar 组件，便于按业务线切换。