# sakura **Repository Path**: cassell-code/sakura ## Basic Information - **Project Name**: sakura - **Description**: 樱花基础框架 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-02-11 - **Last Updated**: 2026-09-18 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README

Release JDK License Spring Cloud Spring Boot
Upstream

## sakura 微服务开发平台 * 由 **SpringBlade** 微服务版重命名而来，采用前后端分离的模式，前端可对接 [Saber](https://gitee.com/smallc/Saber)(基于 Vue3、Element-Plus)，当前仓库以纯后端为主 * 后端采用 Spring Cloud 全家桶，并对其基础组件做了高度封装，独立开源出一套框架：`sakura-tool`(即本仓库 `sakura-tool/` 下的 16 个 `sakura-core-*` 模块) * 集成 Sentinel，从流量控制、熔断降级、系统负载等多个维度保护服务稳定性 * 注册中心、配置中心选型 Nacos，为工程瘦身的同时加强各模块之间的联动 * 极简封装了多租户底层，用更少的代码换来拓展性更强的 SaaS 多租户系统 * 自研 Secure 模块，采用 JWT 做 Token 认证，可扩展集成 Redis 等细颗粒度控制方案 * 借鉴 OAuth2/Spring Security 设计思路，自研 `sakura-core-secure` 鉴权体系，支持 `@PreAuth` 角色权限与数据权限 * 项目分包明确，规范微服务的开发模式(API/Service 分离 + Feign 契约)，使包与包之间的分工清晰 ## 架构图 ```mermaid flowchart LR subgraph 客户端 A[Saber 前端
Vue3 + Element-Plus] B[knife4j / Swagger2
接口文档] end subgraph 服务发现 / 配置中心 C[Nacos 2.1.2
127.0.0.1:8848] end subgraph 中间件 D[(MySQL 8)] E[(Redis)] F[Sentinel
127.0.0.1:8858] end A -->|HTTP + JWT| G[sakura-service/sakura-system
端口 8106] G --> C G --> D G --> E G --> F G -->|Feign / OpenFeign| G ``` > 当前仓库只实现了 `sakura-system` 一个业务服务。新增服务按 `sakura-service/sakura-system` + `sakura-service-api/sakura-system-api` 的形态复制即可(步骤见下方「新增微服务」)。 ## 核心技术栈 | 技术栈 | 版本 | |----------------------|------------| | Java | 8+ | | Spring | 5.3.31 | | Spring Boot | 2.7.18 | | Spring Cloud | 2021.0.8 | | Spring Cloud Alibaba | 2021.0.5.0 | | Nacos Alibaba | 2.1.2 | | MyBatis-Plus | 3.5.2 | | knife4j(swagger2) | 4.3.0 | | EasyExcel | 2.2.11(可选) | ## 工程结构 ``` sakura/ ├── pom.xml -- 父 POM（依赖管理与插件） ├── sql.sql -- MySQL 建表脚本 ├── CLAUDE.md -- Claude Code 开发规范 ├── sakura-common/ -- 公共模块 │ └── src/main/java/org/sakura/common │ ├── cache -- 缓存键定义（CacheNames） │ ├── constant-- 常量（CommonConstant、LauncherConstant） │ └── launch -- 启动装配（LauncherService） ├── sakura-service-api/ -- 业务契约父模块（Entity / VO / DTO / Feign） │ └── sakura-system-api/ -- 系统管理契约层 │ └── org/sakura/system │ ├── entity/ -- 实体 │ ├── vo/ -- 视图对象 │ ├── dto/ -- 传输对象 │ └── feign/ -- Feign 接口 + Fallback（ISysClient 等） ├── sakura-service/ -- 业务服务父模块 │ └── sakura-system/ -- 系统管理服务（用户/角色/菜单/部门/字典/租户/岗位/参数/区域/客户端） │ └── org/sakura/system │ ├── controller/ -- 接口层（继承 SakuraController） │ ├── service/ -- 业务层（I*Service + impl） │ ├── mapper/ -- 数据层（Mapper 接口 + XML 同包） │ ├── wrapper/ -- 数据转换层（Entity → VO） │ └── feign/ -- Feign 实现类 └── sakura-tool/ -- 自研工具包（16 个 sakura-core-* 子模块） ├── sakura-core-launch/ -- 启动器（SakuraApplication.run 入口、AppConstant） ├── sakura-core-boot/ -- Web/文件/异步/租户基础装配（SakuraController） ├── sakura-core-secure/ -- 鉴权（SakuraUser、@PreAuth） ├── sakura-core-mybatis/ -- MyBatis-Plus 增强（Condition/Query/BaseService） ├── sakura-core-tool/ -- 通用工具（R、Func、CacheUtil、RedisUtil） ├── sakura-core-cloud/ -- Nacos / Sentinel / Seata ├── sakura-core-loadbalancer/ -- 负载均衡（灰度） ├── sakura-core-swagger/ -- knife4j-openapi2 文档装配 ├── sakura-core-datascope/ -- 数据权限 └── sakura-core-log / core-oss / core-social / core-test / core-transaction / core-report / core-develop ``` ## 快速开始 ### 1. 启动中间件 | 中间件 | 地址 | 说明 | |------|------|------| | Nacos | `127.0.0.1:8848` | 服务注册与配置中心(namespace `f447a694-519a-4255-95f9-bcbb5a5d636`,config prefix `sakura`) | | MySQL | 本机 | 建库后执行根目录 `sql.sql` 初始化表结构 | | Redis | `127.0.0.1:6379` | 缓存(RedisUtil) | | Sentinel | `127.0.0.1:8858`(可选) | 熔断限流控制台 | ### 2. 配置环境变量 应用 yml 里的数据源占位符是 `sakura.datasource.*`,需用同名环境变量注入: ```bash export sakura.datasource.dev.url="jdbc:mysql://127.0.0.1:3306/sakura?useUnicode=true&characterEncoding=utf-8&useSSL=false&serverTimezone=Asia/Shanghai" export sakura.datasource.dev.username="root" export sakura.datasource.dev.password="your_password" export sakura.env="dev" # logback 按此选择日志配置 ``` ### 3. 启动服务 在 IDE 中直接运行 `sakura-service/sakura-system` 的 `org.sakura.system.SystemApplication#main`(dev profile)。 启动后访问接口文档:`http://127.0.0.1:8106/doc.html`(knife4j)。 ## 常用命令 本机无全局 `mvn`,用 IDEA 内置 Maven: ```bash # 编译全部模块（跳过测试） sh "/Applications/IntelliJ IDEA.app/Contents/plugins/maven/lib/maven3/bin/mvn" clean install -DskipTests # 仅构建 system 服务及其依赖 sh "/Applications/IntelliJ IDEA.app/Contents/plugins/maven/lib/maven3/bin/mvn" clean install -pl sakura-service/sakura-system -am -DskipTests # 跑全部测试 sh "/Applications/IntelliJ IDEA.app/Contents/plugins/maven/lib/maven3/bin/mvn" test ``` ## 新增微服务 参考 `sakura-system` 复制一份: 1. `sakura-service/pom.xml` 的 `` 加新模块 2. `sakura-service-api/pom.xml` 同理,加一个 `sakura--api` 放 Feign 接口和共享 DTO 3. 新建 `sakura-service/sakura-/`,依赖 `sakura--api`、需要的 `sakura-core-*` 4. 启动类仿 `SystemApplication` 写 `XxxApplication`,在 `AppConstant` 加 `APPLICATION__NAME` 5. 业务包路径用 `org.sakura.` 详细步骤见 [CLAUDE.md](CLAUDE.md#15-新增微服务的步骤)。 ## 关联项目 | 简介 | 地址 | |---------|------| | 上游框架 SpringBlade | [https://gitee.com/smallc/SpringBlade](https://gitee.com/smallc/SpringBlade) | | 核心工具 blade-tool | [https://gitee.com/smallc/blade-tool](https://gitee.com/smallc/blade-tool) | | 前端框架 Saber(Vue3) | [https://gitee.com/smallc/Saber](https://gitee.com/smallc/Saber) | | 前端框架 Sword(React) | [https://gitee.com/smallc/Sword](https://gitee.com/smallc/Sword) | ## 开源协议 Apache Licence 2.0 ([英文原文](http://www.apache.org/licenses/LICENSE-2.0.html)) Apache Licence 是著名的非盈利开源组织 Apache 采用的协议。该协议和 BSD 类似，同样鼓励代码共享和尊重原作者的著作权，同样允许代码修改，再发布(作为开源或商业软件)。 ## 用户权益 * 允许免费用于学习、毕设、公司项目、私活等，但请保留源码作者信息。 * 对未经过授权和不遵循 Apache 2.0 协议二次开源或者商业化我们将追究到底。 * 参考请注明：参考自 SpringBlade：[https://gitee.com/smallc/SpringBlade](https://gitee.com/smallc/SpringBlade)。