5.8 KiB

Raw Blame History

全局配置与用户配置模块设计文档

日期：2026-04-16
范围：实现全局配置与当前登录用户配置的读写能力（写走 service + API，读走快捷函数）
目标：在不破坏现有请求处理结构的前提下，提供统一、可扩展、可维护的配置能力

1. 需求边界

1.1 必做功能

支持全局配置读写
支持当前登录用户私有配置读写
读取提供快捷函数，支持优先级合并（用户 > 全局 > 默认）
写入仅允许通过 service + API
在请求上下文中提供只读配置门面，便于 API 快捷读取

1.2 明确不做

跨用户配置代写（如普通接口直接写任意 userId）
复杂配置权限系统（本期仅预留管理员写全局入口）
进程级缓存、分布式缓存和缓存失效广播
配置版本历史与审计回溯

2. 总体架构

模块分为四层：

Schema / Migration
- 存储全局配置和用户配置数据。
Config Registry
- 定义配置键、默认值、作用域、值类型、是否允许用户覆盖。
Config Service
- 提供校验、读取、合并、写入能力。
Request Context Facade
- 在 event.context 上暴露只读配置快捷函数。

2.1 关于 `defineWrappedResponseHandler` 的定位

defineWrappedResponseHandler 应保持“响应包装 + 统一错误处理”为主职责。
配置门面的初始化逻辑优先放到 Nitro plugin（请求生命周期）中。
defineWrappedResponseHandler 仅做轻介入（例如类型收敛或兜底检查），不承载复杂装配逻辑。

该方案可保留快捷读取体验，同时避免 handler 职责膨胀。

3. 数据模型设计

采用“注册表强约束 + key-value 存储扩展”的混合模式。

3.1 全局配置表 `app_configs`

key：主键
value：序列化后的值（字符串）
valueType：值类型标记（string | number | boolean | json）
updatedAt：更新时间

3.2 用户配置表 `user_configs`

userId：用户 ID
key：配置键
value：序列化后的值（字符串）
valueType：值类型标记
updatedAt：更新时间
唯一键：(userId, key)

说明：

app_configs 与 user_configs 语义分离，便于维护和查询。
用户配置覆盖全局配置时，仅影响对应用户，不改写全局值。

4. 配置注册表（Registry）

注册表用于定义“正式支持的配置项”，避免任意 key 无约束扩散。

每个配置项包含：

key
scope：global | user | both
valueType：string | number | boolean | json
defaultValue
userOverridable
可选 validate(value) 业务校验

设计原则：

核心配置通过注册表获得稳定约束（类型、默认值、可覆盖规则）。
底层表结构保持 key-value 形态，支持后续扩展而不频繁改表结构。

5. 读取设计

5.1 请求内读取（主路径）

通过 event.context.config 提供只读能力：

getGlobal(key)：读取全局配置，不存在则返回默认值
getUser(key)：读取当前登录用户私有配置；未登录返回 undefined
get(key)：按 user -> global -> default 顺序返回

5.2 请求级缓存

在单次请求内使用轻量内存缓存（如 Map）：

同一 key 多次读取不重复查库
get / getUser / getGlobal 共用缓存结果
缓存生命周期限定在当前请求

5.3 非请求场景读取

提供 service 级快捷函数（不依赖 event.context），用于定时任务或后台逻辑：

readGlobalConfig(key)
readMergedUserConfig(userId, key)

6. 写入设计（仅 service + API）

6.1 全局配置写入

接口建议：PUT /api/config/global

入参：{ key, value }
逻辑：校验 key、scope、value 后执行 upsert
权限：管理员能力（本期可先预留校验位置）

6.2 当前用户配置写入

接口建议：PUT /api/config/me

入参：{ key, value }
前置：要求已登录
逻辑：校验 key 可否用户覆盖、校验值合法性后 upsert

6.3 用户配置重置

接口建议：DELETE /api/config/me/:key

删除用户侧覆盖项
读取时自动回退全局值或默认值

7. 错误模型

建议统一业务错误码（命名可按项目规范微调）：

CONFIG_KEY_NOT_FOUND
CONFIG_SCOPE_INVALID
CONFIG_VALUE_INVALID
CONFIG_FORBIDDEN
UNAUTHORIZED

目标：

调用方可稳定识别错误类型
日志与监控便于聚合分析

8. 代码落点建议

server/service/config/registry.ts
- 配置项定义与校验规则
server/service/config/index.ts
- 读取、合并、写入 service
server/plugins/04.config-context.ts（或补充 00.global.ts）
- 注入 event.context.config 只读门面
server/api/config/global.put.ts
- 全局配置写入
server/api/config/me.put.ts
- 当前用户配置写入
server/api/config/me/[key].delete.ts
- 删除用户覆盖项
packages/drizzle-pkg/...
- app_configs / user_configs schema 与迁移

9. 验收标准

get(key) 可按 user -> global -> default 正确合并
未登录时 getUser(key) 返回 undefined
全局写入成功后读取立即生效
用户写入后优先覆盖全局值
非法 key 或非法值写入会被拒绝
不允许用户覆盖的 key 在用户接口写入被拒绝

10. 实施顺序建议

增加配置表 schema 与数据库迁移
实现 registry 与 config service
注入请求上下文只读门面（plugin）
实现全局/用户配置写入 API
补充读取、写入、错误分支测试
按验收标准做手工验证

本设计文档结论：在 event.context 扩展配置读取能力是合理的，但应限定为“请求级只读门面”；写入始终通过 service + API，defineWrappedResponseHandler 保持轻职责，不承担复杂上下文装配。

5.8 KiB Raw Blame History