简介

本技术文档面向 DouPHP 的“微博登录插件”开发。当前仓库中 plugin/weibo 目录为空，尚未提供微博 OAuth2.0 的具体实现。为便于后续快速落地，本文基于现有微信登录插件与统一 OAuth 接口契约，给出微博登录的完整设计方案、数据流、安全策略与开发示例路径指引。读者可据此在 plugin/weibo 下创建 Provider/Service，复用系统统一的第三方登录编排能力。

项目结构

• 统一 OAuth 插件契约：位于 core/infra/plugin/contract/ConnectPluginProviderInterface.php，定义了第三方登录插件的统一入口 start/finish 等。
• 参考实现（微信）：位于 plugin/wxlogin，包含 WxloginProvider.php、WxloginService.php、manifest.php，展示了如何按 UA 选择不同 appid、发起授权、处理回跳、获取用户信息并对接 SnsLoginService。
• API 端小程序微信登录：位于 api/controller/user/WeixinController.php，展示 code 换 session、绑定 user_sns、生成 token 的流程，可作为 PC 端 OAuth 流程之外的补充参考。

graph TB
A["前端/客户端"] --> B["插件路由 /plugin/{id}/start"]
B --> C["ConnectPluginProviderInterface<br/>start()"]
C --> D["具体 Provider<br/>如 WxloginProvider"]
D --> E["具体 Service<br/>如 WxloginService"]
E --> F["第三方平台OAuth<br/>微信/微博"]
F --> G["回调 /plugin/{id}/finish"]
G --> H["SnsLoginService<br/>统一登录编排"]
H --> I["用户会话/令牌"]

核心组件

• ConnectPluginProviderInterface：定义第三方登录插件的统一契约，包括插件 ID、元信息、start（发起授权）、finish（处理回跳）。
• WxloginProvider：微信登录插件的 Provider，负责将 start/finish 委托给服务层。
• WxloginService：微信登录业务逻辑，包括按 UA 选择 appid、构造授权 URL、校验 state、换取 access_token/openid、拉取用户信息、组装 sns 数据并调用 SnsLoginService 完成登录编排。
• manifest.php：声明插件归属 connect 分组及 Provider 类名。
• WeixinController：API 端小程序微信登录控制器，用于对比理解 code 换 session、绑定 user_sns、发放 token 的流程。

架构总览

下图展示从前端触发到后端完成登录的端到端流程，以及微博登录应遵循的接入点。

sequenceDiagram
participant U as "用户"
participant FE as "前端页面"
participant PL as "插件路由"
participant PR as "微博Provider(待实现)"
participant PS as "微博Service(待实现)"
participant WB as "微博开放平台"
participant SL as "SnsLoginService"
participant US as "用户会话/令牌"
U->>FE : 点击“微博登录”
FE->>PL : 访问 /plugin/weibo/start
PL->>PR : 调用 start()
PR->>PS : 构建授权URL(state, scope, redirect_uri)
PS-->>FE : 返回跳转URL
FE->>WB : 打开微博授权页
WB-->>PL : 回调 /plugin/weibo/finish?code&state
PL->>PR : 调用 finish(payload)
PR->>PS : 校验state、换取access_token/openid、拉取用户信息
PS->>SL : resolve(sns, profile, loginIdMode, nobind)
SL-->>US : 建立会话/发放令牌
US-->>FE : 登录成功跳转

详细组件分析

统一 OAuth 插件契约（ConnectPluginProviderInterface）

• 职责：定义所有第三方登录插件必须实现的接口，确保系统对 start/finish 的统一调度。
• 关键点：
  • pluginId：插件唯一标识，用于路由与配置隔离。
  • meta：插件名称、描述、版本、分组、允许客户端类型、配置字段 schema。
  • start：返回授权页跳转 URL，需携带 state、scope、redirect_uri。
  • finish：接收第三方回调参数，完成鉴权与用户信息获取，最终交由 SnsLoginService 完成登录编排。

微信登录插件参考（WxloginProvider 与 WxloginService）

• Provider：仅做委托，保持轻量；实际逻辑集中在 Service。
• Service：
  • 按 UA 判断公众号或开放平台，选择对应 appid/appsecret。
  • 生成 state 并存入 Session，防止 CSRF。
  • 构造授权 URL（PC 扫码或公众号内授权），scope 使用平台标准范围。
  • 回调时校验 state，换取 access_token 与 openid，再拉取用户信息。
  • 根据配置决定以 openid 或 unionid 作为登录主键。
  • 清洗昵称等敏感字段，组装 sns 数据后调用 SnsLoginService.resolve。

flowchart TD
Start(["开始"]) --> UA["识别UA选择AppID/Secret"]
UA --> State["生成state并写入Session"]
State --> BuildUrl["拼接授权URL<br/>含state/scope/redirect_uri"]
BuildUrl --> Redirect["重定向至第三方授权页"]
Redirect --> Callback{"收到回调"}
Callback --> |校验state| Token["换取access_token/openid"]
Token --> UserInfo["拉取用户信息"]
UserInfo --> MapSNS["映射为sns数据结构"]
MapSNS --> Resolve["调用SnsLoginService.resolve"]
Resolve --> End(["结束"])

API 端小程序微信登录（WeixinController）

• 作用：小程序侧通过 jscode2session 获取 openid/session_key，结合手机号解密等能力完成登录与绑定。
• 要点：
  • 频率限制与错误审计。
  • 支持 unionid 模式与手机号绑定。
  • 自动建号与 user_sns 绑定，发放 API Token。

依赖关系分析

• 微博插件（待实现）将依赖：
  • ConnectPluginProviderInterface：统一入口。
  • SnsLoginService：统一登录编排（账号匹配、新建、绑定、发放令牌）。
  • 配置中心：读取 plugin/weibo 的配置项（appkey、appsecret、回调地址、scope 等）。
  • HTTP 客户端：请求微博开放平台 API（access_token、用户信息等）。

graph LR
IF["ConnectPluginProviderInterface"] --> P["微博Provider(待实现)"]
P --> S["微博Service(待实现)"]
S --> SL["SnsLoginService"]
S --> CFG["插件配置"]
S --> HTTP["HTTP客户端"]
HTTP --> WB["微博开放平台API"]

性能考虑

• 网络请求：
  • 对第三方 API 调用增加超时与重试上限，避免阻塞请求线程。
  • 缓存 access_token 与用户信息（注意过期时间），减少重复请求。
• 并发与限流：
  • 对回调接口进行 IP 级速率限制，防止滥用。
• 资源占用：
  • 头像等大图片建议异步下载与本地缓存，避免同步阻塞。
• 数据库：
  • 批量写入 user_sns 与用户资料时尽量事务化，减少锁竞争。

故障排查指南

• 常见错误定位：
  • state 校验失败：检查 Session 是否被清理或跨域丢失。
  • code 无效或过期：确认回调地址与授权页一致，且 code 一次性有效。
  • 无法获取 unionid：检查登录主键模式配置与平台返回。
  • 用户信息为空：检查权限范围 scope 是否包含必要字段。
• 日志与审计：
  • 记录关键步骤（授权跳转、回调、token 交换、用户信息拉取）的成功/失败。
  • 对异常分支输出可读的错误码与提示，便于前端展示。

结论

当前仓库未提供微博登录插件的具体实现，但已具备完善的统一 OAuth 插件契约与微信登录参考实现。按照本文方案，可在 plugin/weibo 下快速创建 Provider/Service，复用 SnsLoginService 完成账号匹配、新建、绑定与令牌发放。实施时需重点关注 state 防重放、access_token 管理、权限范围控制、头像与隐私数据处理，以及合规性要求。

附录

微博开放平台接入清单（规划）

• 应用创建：
  • 在“微博开放平台”创建网站应用，获取 App Key 与 App Secret。
  • 设置回调地址（Redirect URI），需与插件配置一致。
• 权限范围（scope）：
  • 基础：users/show（用户基本信息）、statuses/share（分享，可选）。
  • 扩展：依据业务需要申请粉丝数、关注列表等权限。
• 前端集成：
  • 引入微博 JS SDK，初始化 client_id 与 redirect_uri。
  • 调用登录方法，跳转到微博授权页。
• 后端处理：
  • 在 finish 回调中校验 state，用 code 换取 access_token。
  • 调用 users/show 获取用户基本信息（昵称、头像、UID）。
  • 根据配置以 uid 或 unionid 模式匹配/新建用户，写入 user_sns。
  • 通过 SnsLoginService 完成登录与会话/令牌发放。
• 数据安全与合规：
  • 最小化采集原则：仅请求必要 scope。
  • 敏感信息脱敏：头像存储本地或 CDN，避免直链泄露。
  • 隐私设置：尊重用户公开范围，不可见字段默认隐藏。
  • 合规性：遵守微博平台协议与个人信息保护法规。