发布日期：2026-06-25
版本升级：全模块 1.1.x → 1.2.0
最低 JDK 版本：JDK 17+（如需 JDK8 兼容请使用 1.0.7 及以下版本）

总体数据

一、新增了哪些

1. wiki-datasource — MyBatis 主从读写能力（核心）

2. socket/wiki-sse — SSE 模块（全新）

• SseEmitterConnectionService — SSE 连接管理

• SseEmitterCallback — 发布订阅回调

• EmitterConstant — 常量定义

3. config/ — 配置中心模块重组

• config/wiki-config — 自 wiki-config 迁出

• config/wiki-nacos-config — Nacos 配置

• config/wiki-nacos-cloud-config — Nacos Cloud 配置

• ConfigureRefreshController — 配置刷新接口

4. security/wiki-oauth2 — OAuth2 监控与事件

• MetricsConfig — Metrics 监控

• TokenEventService / AuthorizationEventService — Token 与授权事件

• AuthEventListener — 认证事件监听

• MetricOAuth2AuthorizationServiceImpl — 带监控的授权服务

• CustomOauth2AuthorizationService — 重构后的授权服务接口

5. wiki-util — HTTP 工具

• HttpUtils — 新增 HTTP 请求工具类（约 400 行）

6. wiki-security — 用户与机构

• IUserDetailsService — 用户详情服务接口

• 切换机构相关接口（需业务端实现）

• SecurityUserEntity 多机构支持重构

7. 实体字段

• AbstractUserEntity — 增加员工 ID

• OrganizationEntity — 增加统一社会信用代码

8. 脚本与文档

• wiki.ps1 — Windows 构建脚本

• README.md / README.en.md — 文档大改

• assets/wiki.png — 项目配图更新

二、优化了哪些

wiki-datasource（重点优化）

1. 配置绑定

   • 去掉 MybatisConfig 上多余的 @Configuration，避免重复 Bean、配置读不到

   • Mapper 扫描改为 Environment + Binder，解决 BeanDefinitionRegistryPostProcessor 过早读配置、@RefreshScope 报错等问题

2. 主从切换规则

   • 有 @Master → 主库

   • 有 @Slave → 从库

   • 无注解 → 默认主库（不再靠类名含 slave 猜测）

   • 每次切换打 INFO 日志：数据源切换: MASTER/SLAVE -> xxxMapper.method()

3. 双 SqlSessionFactory

   • primarySessionFactory（主库）+ sessionFactory（从库）

   • 主从可分别配置 Mapper 包和 XML 路径

   • MybatisConfig 支持 master / slave 嵌套配置

4. 稳定性

   • sqlSessionTemplate 明确绑定 primarySessionFactory

   • SqlSessionFactory 初始化失败直接抛异常，避免返回 null

wiki-minio

• MinioUtils 方法全部改为 静态方法，调用更简单（约 1100 行重构）

wiki-oauth2

• 授权服务拆分，增加 Metrics 与事件体系，便于监控和排查

wiki-cloud

• 新增 LoadBalancerRequestTransformerConfig，负载均衡请求转换

依赖与协议

• MySQL 驱动改为 test scope，避免 GPL 协议冲突

• LICENSE 更新为木兰宽松许可证

三、调整了哪些

四、修改 / 修复了哪些

五、wiki-datasource 变更一览

新增文件

@Master.java / @Slave.java
DataSourceAspect.java
DynamicDataSource.java / DataSourceContextHolder.java
DataSourceType.java
MapperPrimaryScannerConfiguration.java
MapperScannerConfiguration.java
MybatisMapperScanSupport.java

重点修改

主从切换逻辑

@Master 注解存在  → MASTER
@Slave  注解存在  → SLAVE
两者都没有        → MASTER（默认）

数据源切换日志

每次 Mapper 方法调用前输出 INFO 日志：

数据源切换: MASTER -> com.xxx.mapper.UserMapper.selectById()
数据源切换: SLAVE  -> com.xxx.mapper.UserMapper.selectList()

六、业务侧配置与使用

application.yml 配置示例

spring:
  datasource:
    # 公共 Mapper 扫描包（主从共用）
    mybatis-mapper:
      - com.framewiki.example.mapper
    # 公共 Mapper XML 路径
    mybatis-mapper-xml:
      - /mybatis/**/*.xml
    # Druid 连接池参数（建议配置）
    max-active: 20
    initial-size: 5
    min-idle: 5
    filters: stat,wall
    master:
      url: jdbc:mysql://host:3306/db?characterEncoding=utf8&serverTimezone=Asia/Shanghai
      username: root
      password: your_password
      driver-class-name: com.mysql.cj.jdbc.Driver
    slave:
      url: jdbc:mysql://host:3306/db?characterEncoding=utf8&serverTimezone=Asia/Shanghai
      username: root
      password: your_password
      driver-class-name: com.mysql.cj.jdbc.Driver

Mapper 注解用法

// 默认主库，无需加注解
public interface RmsUserMapper {
    RmsUser selectById(Long id);
}

// 显式走从库
public interface RmsUserQueryMapper {
    @Slave
    List<RmsUser> selectList();
}

// 从库 Mapper 上标了 @Slave，但某个写操作强制走主库
@Slave
public interface RmsUserSlaveMapper {
    @Master
    int updateStatus(Long id);
}

启用方式

在启动类上添加：

@EnableAutoMybatis
@SpringBootApplication
public class Application { }

MySQL 驱动依赖（必须自行引入）

wiki-datasource 模块内 mysql-connector-j 为 test scope，业务项目需自行添加：

<dependency>
    <groupId>com.mysql</groupId>
    <artifactId>mysql-connector-j</artifactId>
</dependency>

若未引入，会出现 ClassNotFoundException: com.mysql.cj.jdbc.Driver，这与配置是否读取成功无关。

七、模块变更文件统计（按目录）

关于维基框架

维基框架（Wiki Framework）是一套面向复杂业务场景的轻量级开发框架，支持多语言、多协议、多部署形态。适用于企业级应用开发、微服务架构、云原生部署等场景。

• 官网：https://framewiki.com
• Gitee：https://gitee.com/wiki-framework
• GitHub：https://github.com/wiki-framework
• 示例项目：https://gitee.com/cdkjframework/framewiki-example
• 📄 许可证：MulanPSL-2.0（木兰宽松许可证，第2版）