跳转至

认证授权微服务 - 总体规划

📋 项目背景

在现代软件开发中，几乎每个项目都需要实现用户认证和权限管理功能。这些功能虽然重要，但实现起来往往耗时耗力，且容易出现安全漏洞。为了解决这个痛点，我们决定开发一个**企业级Spring Boot脚手架Starter**。

核心理念

"一个依赖，开箱即用 - 既有基础框架，又有认证授权"

🎯 项目定位

打造一个企业级的Spring Boot脚手架Starter，集成基础框架能力和认证授权功能

目标用户

  1. Java开发者 - 需要快速集成认证授权的后端开发者
  2. 架构师 - 负责设计企业级应用架构的技术专家
  3. 创业团队 - 需要快速构建MVP的小团队
  4. 企业开发团队 - 需要统一认证中心的大中型企业

解决的问题

问题 传统方案 我们的方案
开发周期长 每个项目都要重新开发认证功能 引入SDK，几行配置即可使用
基础代码重复 每个项目都要写响应体、异常处理 基础框架开箱即用
安全性难保证 自己实现容易出现安全漏洞 基于成熟的安全框架和最佳实践
功能不完善 往往只实现基础功能 提供企业级完整功能
维护成本高 每个项目单独维护 统一维护和升级
缺乏标准化 各个项目实现方式不统一 统一编码标准和最佳实践

🏗️ 整体架构

三层架构

┌─────────────────────────────────────────────────────┐
│                    应用层                             │
│  (业务系统通过SDK或API调用认证服务)                     │
└────────────────┬────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────┐
│                  服务层                               │
│  认证授权微服务 (Auth Boot Starter)                    │
│  - 基础框架  - 认证授权  - 权限管理  - 多租户          │
└────────────────┬────────────────────────────────────┘
                 │
┌────────────────▼────────────────────────────────────┐
│                  存储层                               │
│  MySQL (持久化)  +  Redis (缓存)                      │
└─────────────────────────────────────────────────────┘

模块划分

auth-boot-starter/                          # 项目根目录
├── pom.xml                                 # 父POM
│
├── auth-boot-starter-common/               # 基础框架 - 公共模块 ⭐
│   ├── exception/                          # 异常体系
│   ├── model/                              # 通用模型（响应体、分页）
│   ├── util/                               # 工具类
│   └── annotation/                         # 通用注解
│
├── auth-boot-starter-web/                  # 基础框架 - Web增强 ⭐
│   ├── config/                             # Web配置（MVC、CORS、Jackson）
│   ├── interceptor/                        # 拦截器
│   └── filter/                             # 过滤器
│
├── auth-boot-starter-mybatis/              # 基础框架 - 持久层 ⭐
│   ├── config/                             # MyBatis Plus配置
│   ├── handler/                            # 自动填充、多租户
│   └── service/                            # 基础CRUD
│
├── auth-boot-starter-redis/                # 基础框架 - 缓存 ⭐
│   ├── config/                             # Redis配置
│   ├── service/                            # Redis工具
│   └── lock/                               # 分布式锁
│
├── auth-boot-starter-security/             # 认证授权 - 核心 ⭐⭐⭐
│   ├── jwt/                                # JWT处理
│   ├── annotation/                         # 安全注解
│   ├── context/                            # 用户上下文
│   └── service/                            # 认证服务
│
├── auth-boot-starter-server/               # 认证授权 - 服务端 ⭐⭐
│   ├── controller/                         # 认证接口
│   ├── service/                            # 用户、角色、权限管理
│   ├── mapper/                             # 数据访问
│   └── entity/                             # 实体类
│
├── auth-boot-starter-client/               # 认证授权 - 客户端SDK ⭐⭐
│   ├── autoconfigure/                      # 自动配置
│   ├── interceptor/                        # 认证拦截器
│   └── aspect/                             # 权限切面
│
├── auth-boot-starter/                      # 整合Starter ⭐⭐⭐
│   └── autoconfigure/                      # 总自动配置
│
├── auth-boot-example/                      # 示例项目
│   ├── example-server/                    # 服务端示例
│   └── example-client/                    # 客户端示例
│
├── docs/                                   # 文档
└── scripts/                                # 数据库脚本

📦 模块说明

基础框架模块（可独立使用）

模块 说明 主要功能
common 公共基础 统一响应体、异常处理、分页、工具类
web Web增强 MVC配置、CORS、拦截器、链路追踪
mybatis 持久层 MyBatis配置、自动填充、基础CRUD
redis 缓存 Redis工具、分布式锁、缓存服务

认证授权模块

模块 说明 主要功能
security 安全核心 JWT、OAuth2、权限注解、用户上下文
server 认证服务端 用户管理、角色权限、认证接口
client 认证客户端 SDK、拦截器、自动配置

整合模块

模块 说明
auth-boot-starter 整合所有模块的总starter，一个依赖全搞定

🎯 使用场景

场景一：只用基础框架（不需要认证）

适合：不需要认证的后台管理系统、内部工具

<dependency>
    <groupId>cn.zhangziming</groupId>
    <artifactId>auth-boot-starter-common</artifactId>
</dependency>
<dependency>
    <groupId>cn.zhangziming</groupId>
    <artifactId>auth-boot-starter-web</artifactId>
</dependency>

获得能力： - ✅ 统一响应体 Result<T> - ✅ 统一异常处理 - ✅ 统一分页 PageResult<T> - ✅ Web增强（CORS、链路追踪）

场景二：认证服务端（提供认证服务）

适合：作为独立的认证中心

<dependency>
    <groupId>cn.zhangziming</groupId>
    <artifactId>auth-boot-starter-server</artifactId>
</dependency>

auth-boot:
  server:
    enabled: true
  security:
    jwt:
      secret: your-secret-key

获得能力： - ✅ 完整的认证服务 - ✅ 用户管理API - ✅ 角色权限管理API - ✅ OAuth 2.0支持

场景三：认证客户端（业务系统）

适合：需要认证的业务系统

<dependency>
    <groupId>cn.zhangziming</groupId>
    <artifactId>auth-boot-starter-client</artifactId>
</dependency>

auth-boot:
  client:
    enabled: true
    server-url: http://auth-server:8080
    client-id: your-client-id

获得能力： - ✅ 注解式权限验证 @RequirePermission - ✅ 用户上下文 UserContext - ✅ Token自动续期 - ✅ 权限拦截器

场景四：一体化（推荐快速开始）

适合：快速开发、中小型项目

<!-- 一个依赖全搞定 -->
<dependency>
    <groupId>cn.zhangziming</groupId>
    <artifactId>auth-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

auth-boot:
  common:
    enabled: true      # 基础框架
  web:
    enabled: true      # Web增强
  mybatis:
    enabled: true      # 数据库
  redis:
    enabled: true      # Redis
  security:
    enabled: true      # 认证授权
  server:
    enabled: true      # 作为认证服务端
  client:
    enabled: false     # 不作为认证客户端

获得能力： - ✅ 所有基础框架能力 - ✅ 所有认证授权能力 - ✅ 快速启动，立即可用

📊 功能规划

核心功能矩阵

模块 功能 优先级 状态 目标版本
基础框架
Common 统一响应体、异常处理 P0 ⏳ 规划中 v0.1.0
Common 统一分页 P0 ⏳ 规划中 v0.1.0
Common 工具类集合 P1 ⏳ 规划中 v0.1.0
Web MVC配置、CORS P0 ⏳ 规划中 v0.1.0
Web 链路追踪、请求日志 P1 ⏳ 规划中 v0.2.0
MyBatis 基础配置 P0 ⏳ 规划中 v0.1.0
MyBatis 自动填充 P1 ⏳ 规划中 v0.2.0
Redis Redis工具类 P1 ⏳ 规划中 v0.3.0
Redis 分布式锁 P2 ⏳ 规划中 v0.3.0
认证授权
用户管理 用户CRUD P0 ⏳ 规划中 v0.1.0
认证 JWT认证 P0 ⏳ 规划中 v0.1.0
认证 OAuth 2.0 P1 ⏳ 规划中 v0.4.0
认证 单点登录 P1 ⏳ 规划中 v0.4.0
认证 第三方登录 P2 ⏳ 规划中 v0.9.0
权限 RBAC权限模型 P0 ⏳ 规划中 v0.2.0
权限 数据权限 P2 ⏳ 规划中 v1.1.0
多租户 租户管理 P1 ⏳ 规划中 v0.5.0
多租户 数据隔离 P1 ⏳ 规划中 v0.5.0
安全 验证码 P1 ⏳ 规划中 v0.7.0
安全 登录锁定 P1 ⏳ 规划中 v0.3.0
日志 登录日志 P1 ⏳ 规划中 v0.8.0
日志 操作日志 P2 ⏳ 规划中 v0.8.0
SDK Spring Boot Starter P0 ⏳ 规划中 v0.6.0
管理后台 前端界面 P2 ⏳ 规划中 v1.2.0

优先级说明: - P0: 核心功能，必须实现 - P1: 重要功能，优先实现 - P2: 增强功能，后续实现

📝 基础框架标准

1. 统一响应体

@Data
public class Result<T> implements Serializable {
    private Integer code;        // 状态码
    private String message;      // 提示信息
    private T data;              // 数据
    private Long timestamp;      // 时间戳
    private String traceId;      // 链路追踪ID

    public static <T> Result<T> success(T data) {
        Result<T> result = new Result<>();
        result.setCode(200);
        result.setMessage("success");
        result.setData(data);
        result.setTimestamp(System.currentTimeMillis());
        return result;
    }

    public static <T> Result<T> error(Integer code, String message) {
        Result<T> result = new Result<>();
        result.setCode(code);
        result.setMessage(message);
        result.setTimestamp(System.currentTimeMillis());
        return result;
    }
}

2. 统一异常处理

@RestControllerAdvice
public class GlobalExceptionHandler {

    // 业务异常
    @ExceptionHandler(BusinessException.class)
    public Result<?> handleBusinessException(BusinessException e) {
        log.error("业务异常: {}", e.getMessage());
        return Result.error(e.getCode(), e.getMessage());
    }

    // 参数校验异常
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<?> handleValidationException(MethodArgumentNotValidException e) {
        String message = e.getBindingResult().getFieldErrors().stream()
            .map(error -> error.getField() + ": " + error.getDefaultMessage())
            .collect(Collectors.joining(", "));
        return Result.error(400, message);
    }

    // 系统异常
    @ExceptionHandler(Exception.class)
    public Result<?> handleException(Exception e) {
        log.error("系统异常", e);
        return Result.error(500, "系统异常，请联系管理员");
    }
}

3. 统一分页

@Data
public class PageRequest implements Serializable {
    @Min(value = 1, message = "页码最小为1")
    private Integer pageNum = 1;

    @Min(value = 1, message = "每页大小最小为1")
    @Max(value = 100, message = "每页大小最大为100")
    private Integer pageSize = 10;

    private String orderBy;
    private String sortOrder = "desc";
}

@Data
public class PageResult<T> implements Serializable {
    private Long total;          // 总记录数
    private Integer pageNum;     // 当前页码
    private Integer pageSize;    // 每页大小
    private Integer pages;       // 总页数
    private List<T> list;        // 数据列表
}

4. 基础实体

@Data
public class BaseEntity implements Serializable {
    @TableId(type = IdType.AUTO)
    private Long id;

    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;    // 创建时间

    @TableField(fill = FieldFill.INSERT)
    private Long createBy;               // 创建人

    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;    // 更新时间

    @TableField(fill = FieldFill.INSERT_UPDATE)
    private Long updateBy;               // 更新人

    @TableLogic
    private Integer isDeleted;           // 删除标志
}

🗓️ 时间规划

总体时间线（16周）

Week 1:    项目结构搭建            ▓░░░░░░░░░░░░░░░
Week 2-3:  基础框架开发            ░▓▓░░░░░░░░░░░░░
Week 4-5:  认证授权核心            ░░░▓▓░░░░░░░░░░░
Week 6-7:  RBAC权限体系            ░░░░░▓▓░░░░░░░░░
Week 8:    缓存与性能优化          ░░░░░░░▓░░░░░░░░
Week 9-10: OAuth 2.0              ░░░░░░░░▓▓░░░░░░
Week 11:   多租户支持              ░░░░░░░░░░▓░░░░░
Week 12:   客户端SDK               ░░░░░░░░░░░▓░░░░
Week 13:   安全增强                ░░░░░░░░░░░░▓░░░
Week 14:   日志监控                ░░░░░░░░░░░░░▓░░
Week 15:   示例和文档              ░░░░░░░░░░░░░░▓░
Week 16:   测试和发布              ░░░░░░░░░░░░░░░▓

详细实施步骤

Phase 1: 项目结构搭建（Week 1）

  • 创建Maven多模块项目
  • 配置父POM依赖管理
  • 创建所有子模块
  • 配置模块间依赖关系
  • 搭建CI/CD基础

Phase 2: 基础框架开发（Week 2-3）

  • common模块
  • 统一响应体 Result<T>
  • 统一异常处理
  • 统一分页 PageRequest/PageResult
  • 基础实体 BaseEntity

  • 工具类（JSON、Date、String等）

  • web模块

  • MVC配置
  • CORS配置
  • Jackson配置
  • 链路追踪拦截器

  • 请求日志拦截器

  • mybatis模块

  • MyBatis Plus配置
  • 自动填充Handler
  • 基础Mapper

  • 基础Service

  • redis模块

  • Redis配置
  • Redis工具类
  • 分布式锁

Phase 3: 认证授权核心（Week 4-5）

  • 数据库设计和初始化
  • 用户管理基础功能
  • JWT Token生成和验证
  • 登录登出接口
  • 用户上下文 UserContext

Phase 4-10: 按原计划继续

继续按照之前的路线图实现各个功能模块...

里程碑

版本 里程碑 时间 关键产出
v0.1.0 基础框架可用 Week 3 响应体、异常、分页等基础能力
v0.2.0 MVP版本 Week 5 基础认证功能可用
v0.5.0 Beta版本 Week 11 核心功能完整
v0.6.0 RC版本 Week 12 客户端SDK可用
v1.0.0 正式版本 Week 16 功能完整、文档齐全

💡 技术选型

核心技术栈

技术领域 选型 版本 理由
基础框架 Spring Boot 3.5.7 最新稳定版本，生态完善
安全框架 Spring Security 6.x 行业标准，功能强大
认证协议 JWT 0.12.x 无状态认证
认证协议 OAuth 2.0 2.x 标准协议
数据库 MySQL 8.0+ 成熟稳定，性能优秀
缓存 Redis 7.0+ 高性能，丰富的数据结构
ORM MyBatis Plus 3.5.x 提高开发效率
API文档 Knife4j 4.x Swagger增强版

技术亮点

  1. 模块化设计 - 各模块职责清晰，可独立使用
  2. 基于Spring Boot 3.x - 使用最新技术栈
  3. 无状态认证 - JWT Token，天然支持分布式
  4. 高性能缓存 - Redis缓存用户信息和权限
  5. 标准协议 - OAuth 2.0，可与任何系统集成
  6. 开箱即用 - Spring Boot Starter，自动配置
  7. 企业级标准 - 统一编码规范和最佳实践

📈 质量保证

质量目标

指标 目标 说明
单元测试覆盖率 > 80% 核心业务逻辑必须有测试
集成测试覆盖率 > 60% 关键接口必须有测试
代码质量评分 > 90 SonarQube扫描
接口响应时间(P99) < 100ms 性能测试达标
QPS > 10,000 支持高并发场景
文档完整性 100% 所有功能都有文档

质量保证措施

  1. 代码审查 - 所有代码必须经过Review
  2. 自动化测试 - CI/CD流程中自动运行测试
  3. 性能测试 - 定期进行压力测试
  4. 安全扫描 - 定期进行安全漏洞扫描
  5. 文档先行 - 功能开发前先编写文档

🎓 学习路径

对于新手开发者

  1. 第一步: 阅读 快速开始指南，5分钟体验
  2. 第二步: 跟随示例集成到自己的项目
  3. 第三步: 阅读 SDK使用指南，掌握API
  4. 第四步: 遇到问题查看 常见问题FAQ

对于架构师

  1. 第一步: 阅读 架构设计文档，了解系统架构
  2. 第二步: 阅读 数据库设计文档，了解数据模型
  3. 第三步: 阅读 部署运维文档，规划部署方案
  4. 第四步: 评估是否满足业务需求，提出定制化需求

对于贡献者

  1. 第一步: 阅读本文档，了解整体规划
  2. 第二步: 阅读 开发路线图，了解详细计划
  3. 第三步: Fork项目，搭建开发环境
  4. 第四步: 选择感兴趣的功能模块开始贡献

📊 成功指标

项目成功的标准

  1. 技术指标
  2. ✅ 所有核心功能完成
  3. ✅ 测试覆盖率达标
  4. ✅ 性能测试通过

  5. ✅ 安全审计通过

  6. 产品指标

  7. ✅ 文档完整易懂
  8. ✅ SDK易于集成
  9. ✅ 示例代码丰富

  10. ✅ API设计合理

  11. 社区指标

  12. ⏳ GitHub Stars > 1000
  13. ⏳ 实际项目使用 > 50
  14. ⏳ 社区贡献者 > 10
  15. ⏳ 技术文章分享 > 20

🚀 长期愿景

短期目标（6个月）

  • 完成v1.0.0正式版本
  • 至少10个项目实际使用
  • 完善的文档和示例

中期目标（1年）

  • 发布v2.0.0，支持更多高级特性
  • 社区生态初步建立
  • 成为Spring Boot开发的首选脚手架

长期目标（2-3年）

  • 成为Java生态中最流行的企业级脚手架
  • 支持多语言SDK（Go、Python、Node.js）
  • 企业版商业化运营

🎯 项目命名

推荐名称

  • 项目名: auth-boot-starter（zen = 张的拼音首字母 + en）
  • 包名: cn.zhangziming.auth
  • artifactId前缀: auth-boot-starter-xxx

模块命名规范

cn.zhangziming:auth-boot-starter-common
cn.zhangziming:auth-boot-starter-web
cn.zhangziming:auth-boot-starter-mybatis
cn.zhangziming:auth-boot-starter-redis
cn.zhangziming:auth-boot-starter-security
cn.zhangziming:auth-boot-starter-server
cn.zhangziming:auth-boot-starter-client
cn.zhangziming:auth-boot-starter

🎯 下一步行动

立即开始

  1. 创建项目结构 

    # 创建父项目
mvn archetype:generate \
  -DgroupId=cn.zhangziming \
  -DartifactId=auth-boot-starter \
  -DarchetypeArtifactId=maven-archetype-quickstart

# 创建各个子模块
cd auth-boot-starter
mvn archetype:generate -DgroupId=cn.zhangziming -DartifactId=auth-boot-starter-common
# ... 其他模块

  2. 配置父POM

  3. 配置依赖版本管理
  4. 配置插件

  5. 配置子模块

  6. 开始编码

  7. 先实现common模块的基础能力
  8. 再实现web模块
  9. 逐步完善其他模块

保持联系

  • 📧 Email: support@example.com
  • 💬 技术交流群: [点击加入]
  • 🐛 Bug反馈: [GitHub Issues]
  • 💡 功能建议: [GitHub Discussions]

📚 文档索引

文档 说明 适合人群
00-总体规划 项目整体规划（本文档）⭐ 所有人
01-项目规划 详细功能规划 产品经理、架构师
02-架构设计 技术架构设计 架构师、开发者
03-数据库设计 数据库结构 DBA、后端开发
04-API接口文档 接口详细说明 前端、后端开发
05-部署运维 部署和运维 运维工程师
06-快速开始 快速上手指南 开发者
07-SDK使用指南 SDK详细用法 开发者
08-常见问题 FAQ问答 所有人
09-开发路线图 版本规划和贡献指南 贡献者、管理者
10-编码规范 编码标准和最佳实践 ⭐ 开发者

让我们一起打造最好用的企业级Spring Boot脚手架！ 🚀

本文档最后更新: 2024-10-28