yweb-auth

分类: 测试与安全 | 上传者: yafo-ai | 下载: 0 | 版本: v1.0（最新）

YWeb 认证授权与权限管理规范。在实现用户登录、JWT Token 处理、权限校验、角色管理、组织架构、OAuth 集成等功能时使用。

更新日志: Source: GitHub https://github.com/yafo-ai/yweb-core

目录结构

当前层级: .cursor/skills/yweb-auth/

📄 SKILL.md 2.5 KB

SKILL.md

---
name: yweb-auth
description: YWeb 认证授权与权限管理规范。在实现用户登录、JWT Token 处理、权限校验、角色管理、组织架构、OAuth 集成等功能时使用。
---

# YWeb 认证授权与权限管理规范

## 核心要点

YWeb 提供完整的认证授权体系：

- **双 Token 机制**：Access Token（短期）+ Refresh Token（长期）
- **认证服务基类**：继承 `BaseAuthService` 实现自定义认证
- **一站式认证设置**：`setup_auth()` 快速启用
- **Token 黑名单**：`setup_auth(token_blacklist=True)` 自动集成黑名单检查，登出/踢出时撤销 Token
- **RBAC 权限框架**：基于角色的访问控制，支持树形角色继承
- **缓存优化**：`@cached(orm_model=User)` 缓存用户信息，自动 merge 回 Session 解决 detached 问题
- **M2M 关系缓存失效**：`cache_invalidator.register()` 默认监听 ManyToMany 集合变更（如 roles 增删），自动失效缓存
- **组织架构管理**：`setup_organization()` 快速启用组织管理功能

## 关键编码规范

1. **认证依赖注入**：使用 `auth.get_current_user` 作为 FastAPI 依赖（`setup_auth()` 返回的 `AuthSetup` 对象）
2. **权限检查**：使用权限装饰器或依赖注入，不在 API 层手动检查
3. **Token 处理**：后端使用 `jwt_manager`，前端实现自动刷新机制
4. **用户模型**：认证相关模型遵循框架约定（RoleMixin 等）
5. **缓存 ORM 对象**：使用 `@cached(orm_model=User)` 而非裸 `@cached()`，确保缓存命中时自动 merge 回 Session
6. **缓存失效**：`cache_invalidator.register(Model, func)` 默认 `watch_relationships=True`，自动监听 M2M 集合变更；显式传 `False` 可关闭

## 详细规范文档

| 主题 | 文档路径 |
|------|---------|
| 认证模块完整指南 | `yweb-core/docs/06_auth_guide.md` |
| 认证流程详解（含缓存优化） | `yweb-core/docs/webapi_development_standards/auth_flow_guide.md` |
| JWT Token 前后端规范 | `yweb-core/docs/webapi_development_standards/jwt_auth_guide.md` |
| 权限管理模块（RBAC） | `yweb-core/docs/08_permission_guide.md` |
| 组织架构管理 | `yweb-core/docs/07_organization_guide.md` |

## 工作流程

1. 初次接入认证功能，阅读 `06_auth_guide.md` 了解支持的认证方式
2. 实现 JWT 相关逻辑前，阅读 `jwt_auth_guide.md` 了解双 Token 机制
3. 理解认证流程和缓存策略，阅读 `auth_flow_guide.md`
4. 实现权限控制前，阅读 `08_permission_guide.md`
5. 涉及组织架构管理时，阅读 `07_organization_guide.md`

登录后下载/点赞/收藏 ❤ 2 | ★ 0

yweb-auth

目录结构

SKILL.md

举报内容

提示