用户标识字段使用规范
字数
1280 字
阅读时间
6 分钟
1. 概述
本规范旨在统一MindGuard项目中用户标识字段的使用，确保数据安全性和一致性。项目采用微信小程序+云开发架构，所有用户标识应遵循以下规范。
2. 标识字段定义
2.1 核心标识字段
| 字段名 | 类型 | 用途 | 必填性 | 索引策略 | 使用场景 |
|---|---|---|---|---|---|
_openid | string | 微信用户唯一标识 | 必填 | 唯一索引(UK) | 身份验证、权限控制 |
user_id | 指针id | 业务关联标识 | 必填 | 普通索引(IDX) | 业务逻辑、统计分析 |
_id | string | 文档主键 | 必填 | 主键索引(PK) | 内部标识、文档引用 |
2.2 已废弃字段
| 字段名 | 状态 | 替代方案 | 迁移时间 |
|---|---|---|---|
unionid | 废弃 | 使用_openid | 立即执行 |
openid_hash | 废弃 | 使用_openid | 立即执行 |
3. 使用规范
3.1 身份验证与权限控制
必须使用_openid：
json
{
"read": "_openid == auth.openid || auth.role in ['counselor','ops']",
"write": "_openid == auth.openid || auth.role in ['ops']"
}3.2 业务关联与统计
使用user_id：
- 用于业务逻辑关联
- 用于统计分析
- 用于用户画像
- 用于数据导出
3.3 查询规范
身份验证查询：
javascript
// 正确：使用_openid进行身份验证
const user = await db.collection('users').where({
_openid: auth.openid
}).get();业务逻辑查询：
javascript
// 正确：使用user_id进行业务关联
const tasks = await db.collection('tasks').where({
user_id: userId,
status: 'pending'
}).get();4. 集合字段要求
4.1 用户相关集合字段规范
| 集合类型 | 必填字段 | 可选字段 | 说明 |
|---|---|---|---|
| 用户核心数据 | _openid | user_id | 权限控制为主 |
| 用户业务数据 | _openid, user_id | - | 双字段标识 |
| 系统管理数据 | user_id | _openid | 内部管理为主 |
4.2 各集合具体要求
4.2.1 users集合
_openid: 必填，唯一标识user_id: 必填，业务关联（使用_id值）
4.2.2 业务集合（checkins, journals, tasks, posts, comments）
_openid: 必填，用于权限控制user_id: 必填，用于业务关联
4.2.3 系统集合（suggestions, badges, notifications, reports）
_openid: 必填，用于权限控制user_id: 必填，用于业务关联
4.2.4 特殊集合（feedback, sessions）
_openid: 必填，主要标识user_id: 可选，业务关联
5. 权限控制统一模式
5.1 标准权限控制
json
{
"read": "_openid == auth.openid || auth.role in ['counselor','ops']",
"write": "_openid == auth.openid || auth.role in ['ops']"
}5.2 管理员权限控制
json
{
"read": "auth.role in ['ops','counselor']",
"write": "auth.role in ['ops']"
}5.3 公开内容权限控制
json
{
"read": "status == 'published' || _openid == auth.openid || auth.role in ['moderator','counselor']",
"write": "_openid == auth.openid || auth.role in ['moderator']"
}6. 索引设计规范
6.1 必需索引
_openid_1: 单字段索引，用于身份验证user_id_1: 单字段索引，用于业务查询_openid_1_status_1: 复合索引，用于权限和状态筛选
6.2 推荐索引
user_id_1_status_1: 复合索引，用于业务状态筛选user_id_1_createdAt_-1: 复合索引，用于时间序列查询
7. 代码实现规范
7.1 云函数参数获取
javascript
// 推荐方式
const openid = wxContext.OPENID;
const userAuth = {
openid: openid,
role: auth.role || 'user'
};7.2 数据库查询
javascript
// 用户数据查询
const userData = await db.collection('collection_name').where({
_openid: userAuth.openid
}).get();
// 业务数据查询
const businessData = await db.collection('collection_name').where({
user_id: targetUserId,
_openid: userAuth.openid // 权限验证
}).get();7.3 数据写入
javascript
// 创建记录
const createData = {
_openid: userAuth.openid,
user_id: generateUserId(), // 可选，根据业务需要
// 其他字段...
createdAt: new Date().toISOString(),
createdBy: 'system'
};8. 迁移指南
8.1 现有数据迁移
- 识别问题字段：查找所有使用
unionid的地方 - 替换字段：将
unionid替换为_openid - 更新索引：调整索引策略，确保
_openid有合适索引 - 测试验证：确保权限控制和业务逻辑正常
8.2 代码迁移
- 服务层修改：统一使用
auth.openid进行身份验证 - 前端传递：确保前端正确传递用户标识
- 测试覆盖：添加权限和数据隔离的测试用例
9. 监控与审计
9.1 关键指标
- 权限验证成功率
- 用户标识字段使用一致性
- 查询性能指标
- 数据隔离有效性
9.2 审计日志
- 用户访问日志
- 权限变更日志
- 数据修改日志
- 异常访问日志
10. 附录
10.1 常见错误
- E_FORBIDDEN: 权限验证失败
- E_USER_NOT_FOUND: 用户不存在
- E_INVALID_USER_ID: 用户标识格式错误
10.2 最佳实践
- 优先使用
_openid进行身份验证 - 使用
user_id进行业务关联 - 确保权限控制的严格性
- 定期审查用户标识使用情况
10.3 版本历史
- v1.0 (2024-04-07): 初始版本，统一使用
_openid和user_id - v0.9 (2024-04-07): 废弃
unionid和openid_hash
贡献者
Cai Hongyu