217 lines
6.5 KiB
Markdown
217 lines
6.5 KiB
Markdown
# Logto 受保护 API Mock 联调设计
|
||
|
||
## 背景
|
||
|
||
当前扩展已经具备基础的 Logto 登录能力：
|
||
|
||
- popup 可触发登录和登出
|
||
- background 可通过 `@logto/chrome-extension` 获取 access token
|
||
- 页面功能在未登录时会被 auth gate 拦住
|
||
|
||
但现阶段业务数据仍然来自页面站内接口，尚未真正验证“扩展拿到 Logto access token 后，请求受保护 API”这条链路。后续真实后端将由其他人提供，因此当前阶段的目标不是接入正式接口，而是先在本地完成一套可重复验证的模拟联调方案。
|
||
|
||
## 目标
|
||
|
||
- 新增一个专用于 Logto 受保护 API 的扩展客户端。
|
||
- 扩展请求受保护 API 前，必须先通过 background 获取 access token。
|
||
- 请求时自动附加 `Authorization: Bearer <token>` 请求头。
|
||
- 提供一个本地 mock 受保护 API，用于验证扩展到后端的完整调用链路。
|
||
- 提供自动化测试，分别覆盖：
|
||
- token 注入逻辑
|
||
- mock API 授权成功/失败行为
|
||
|
||
## 非目标
|
||
|
||
- 不接入真实业务后端。
|
||
- 不做真实 JWT 签名校验、JWKS 拉取或资源权限判定。
|
||
- 不修改现有星图页面数据采集逻辑为正式后端模式。
|
||
- 不在本阶段设计复杂的 token 刷新监控或重试策略。
|
||
|
||
## 方案对比
|
||
|
||
### 方案 A：只做本地 mock 后端
|
||
|
||
- 直接搭一个假接口，扩展请求它并观察返回。
|
||
- 优点：最接近最终使用方式。
|
||
- 缺点：如果联调失败，不容易快速判断问题出在 token 注入还是 mock 服务本身。
|
||
|
||
### 方案 B：只做代码级测试
|
||
|
||
- 不起本地服务，只用测试替身验证请求头是否带 token。
|
||
- 优点：实现快，定位问题直接。
|
||
- 缺点：无法证明完整链路可运行。
|
||
|
||
### 方案 C：先代码级测试，再接本地 mock 后端
|
||
|
||
- 先用单元测试锁定 token 注入行为，再起 mock 服务完成真实联调。
|
||
- 优点：定位问题更快，同时保留完整链路验证。
|
||
- 缺点：改动稍多于单一方案。
|
||
|
||
推荐采用方案 C。
|
||
|
||
## 架构设计
|
||
|
||
### 1. 扩展受保护 API 客户端
|
||
|
||
新增一个独立客户端模块，职责如下：
|
||
|
||
- 向 background 发送 `auth:get-access-token` 消息
|
||
- 读取返回的 access token
|
||
- 使用该 token 请求指定后端地址
|
||
- 将接口成功、未授权、网络失败这三类结果转成明确错误
|
||
|
||
这个客户端不直接耦合星图 DOM，也不依赖 popup。它只负责“拿 token 并带 token 发请求”，这样后续替换正式后端时只需要调整接口地址和返回映射。
|
||
|
||
### 2. Background 认证桥接
|
||
|
||
现有 background 已支持 `auth:get-access-token`。本次不改变登录主流程，只把它当作唯一 token 来源：
|
||
|
||
- content script 不直接接触 Logto SDK
|
||
- 所有受保护 API 请求都通过 background 提供 token
|
||
|
||
这样可以保持认证逻辑集中，符合 MV3 扩展的边界约束。
|
||
|
||
### 3. 本地 mock 受保护 API
|
||
|
||
新增一个轻量本地服务作为测试后端，建议职责保持极小：
|
||
|
||
- 暴露固定测试 endpoint，例如 `/api/mock/protected`
|
||
- 检查请求头中是否存在 `Authorization`
|
||
- 如果请求头形如 `Bearer <非空字符串>`，返回固定假数据
|
||
- 如果没有该头，返回 `401`
|
||
|
||
本阶段不要求验证 token 是否来自真实 Logto，只验证“扩展是否按约定附带了 Bearer token”。
|
||
|
||
## 数据流
|
||
|
||
完整调用链路如下：
|
||
|
||
1. 扩展中的业务入口调用受保护 API 客户端
|
||
2. 客户端向 background 发送 `auth:get-access-token`
|
||
3. background 返回当前 access token
|
||
4. 客户端带上 `Authorization: Bearer <token>` 请求本地 mock API
|
||
5. mock API 校验请求头并返回假数据
|
||
6. 客户端将结果回传给调用方
|
||
|
||
失败分支：
|
||
|
||
- 如果 background 没返回合法 token，客户端直接报错，不发请求
|
||
- 如果 mock API 返回 `401`，客户端将其识别为未授权错误
|
||
- 如果请求超时或网络失败，客户端抛出网络错误
|
||
|
||
## 接口设计
|
||
|
||
### 扩展内客户端接口
|
||
|
||
建议客户端提供单一入口，例如：
|
||
|
||
- `loadProtectedMockData()`
|
||
|
||
内部行为：
|
||
|
||
- 先取 token
|
||
- 再发 GET 请求
|
||
- 返回结构化响应对象或抛出明确错误
|
||
|
||
后续替换真实后端时，可以保留同样入口，内部再切换到真实 endpoint。
|
||
|
||
### Mock API 返回
|
||
|
||
成功时返回固定 JSON，例如：
|
||
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"source": "mock-protected-api",
|
||
"message": "authorized",
|
||
"receivedAuthHeader": "Bearer ..."
|
||
}
|
||
```
|
||
|
||
失败时返回：
|
||
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"error": "unauthorized"
|
||
}
|
||
```
|
||
|
||
## 错误处理
|
||
|
||
### 无 token
|
||
|
||
- 判定条件：background 未返回 `auth:token`，或 token 为空字符串
|
||
- 处理方式：立即抛错，提示当前未登录或 token 不可用
|
||
|
||
### 未授权
|
||
|
||
- 判定条件：后端返回 `401` 或 `403`
|
||
- 处理方式：抛出授权失败错误，供上层展示“请重新登录”
|
||
|
||
### 网络失败
|
||
|
||
- 判定条件：fetch 抛异常、连接失败、超时
|
||
- 处理方式：抛出网络错误，不吞掉异常原因
|
||
|
||
## 实现边界
|
||
|
||
建议新增或调整如下模块：
|
||
|
||
### `src/content/market` 下新增受保护 API 客户端
|
||
|
||
- 不替换现有页面接口客户端
|
||
- 独立处理 mock 受保护 API 访问
|
||
- 便于后续把“页面抓取模式”和“后端接口模式”并行保留
|
||
|
||
### `src/shared/auth-messages.ts`
|
||
|
||
- 复用现有 `auth:get-access-token`
|
||
- 若现有消息结构足够，则不新增消息类型
|
||
|
||
### `scripts/` 或独立目录中的 mock 服务
|
||
|
||
- 提供本地测试服务启动脚本
|
||
- 默认监听本地固定端口
|
||
- 返回固定 JSON 结果
|
||
|
||
## 测试策略
|
||
|
||
### 单元测试
|
||
|
||
- 客户端请求前会先获取 access token
|
||
- 拿到 token 后，请求头中包含 `Authorization: Bearer <token>`
|
||
- token 缺失时不会发起 fetch
|
||
- 接口返回 `401` 时抛出未授权错误
|
||
- 接口返回成功时正确解析 JSON
|
||
|
||
### 联调测试
|
||
|
||
- 启动本地 mock 服务后，带 token 请求能成功
|
||
- 不带 token 请求返回 `401`
|
||
- 扩展客户端能读到 mock 返回的假数据
|
||
|
||
## 手动验证
|
||
|
||
1. 构建并加载扩展
|
||
2. 在 popup 中完成 Logto 登录
|
||
3. 启动本地 mock API
|
||
4. 触发扩展中的受保护接口请求
|
||
5. 确认 mock API 收到 `Authorization: Bearer <token>`
|
||
6. 确认扩展端收到成功响应
|
||
|
||
## 迁移到真实后端的路径
|
||
|
||
当真实后端可用时，仅需要替换以下内容：
|
||
|
||
- mock API 基地址
|
||
- 具体 endpoint 路径
|
||
- 返回数据结构映射
|
||
- 若真实后端要求额外 scope，则补充 `auth-config` 中的 scopes
|
||
|
||
核心认证链路保持不变：
|
||
|
||
- 仍由 background 提供 token
|
||
- 仍由独立客户端附带 `Bearer` 请求头
|
||
- 仍按未授权和网络错误分别处理
|