# alpha-cloud

**Repository Path**: packagejava/alpha-cloud

## Basic Information

- **Project Name**: alpha-cloud
- **Description**: 极简微服务框架，用最少的代码元素实现微服务框架，
基于数据驱动开发，根据数据模型定义生成的代码无需人工维护。
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2025-06-11
- **Last Updated**: 2025-06-11

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# alpha-cloud

#### 介绍
极简微服务框架，用最少的代码元素实现微服务框架，
基于数据驱动开发，根据数据模型定义生成的代码无需人工维护。

#### 软件架构
软件架构说明


#### 安装教程

1.  xxxx
2.  xxxx
3.  xxxx

#### 使用说明

1.  xxxx
2.  xxxx
3.  xxxx

#### 参与贡献

1.  Fork 本仓库
2.  新建 Feat_xxx 分支
3.  提交代码
4.  新建 Pull Request


#### 特技

1.  使用 Readme\_XXX.md 来支持不同的语言，例如 Readme\_en.md, Readme\_zh.md
2.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
3.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
4.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
5.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
6.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)


# 1. 目标

* **降配减量**：配置降一半，代码量降一半，降低代码熵。
* **规范化**：代码、流程，统一约束，避免各行其是，增强代码可读性。
* **提升软件质量（研发效率）**：消除重复，减少代码元素。
* **改进用户体验**：统一操作习惯、交互页面优化、改进权限管理。

# 2. 三大原则

1. **<font size=6>精</font>**

> 关键字：**代码是一门艺术**、精致、精品、让人喜欢、引导用户、好习惯会上瘾

2. **<font size=6>简</font>**

> 关键字：**简单设计四原则**、产品操作简单、代码整洁简单、接口简单、简单才能易于扩展和维护

3. **<font size=6>信</font>**

> **代码规范**、流程管理规范、运维运营规范、菜单（接口）权限控制、数据权限控制

# 3. 基础服务合并

**`面临的问题：`**

* 服务器资源紧张，系统长期运行后资源告警。
* 基础服务业务少，却占用过多资源。
* 基础服务拆分过多，服务间耦合性高。

> 基础服务目前不存在拆分使用的场景，因此可以精简为 gateway 和 common 两个服务。

# 4. 实现五个统一

## 4.1 统一组件配置

**`当前坏味道`**

* 存在大量内容和结构都相似（针对同一个组件的配置）的配置类
* 同一个组件的配置不一致，正确的实践无法推广。

**`应对方案`**

> 组件配置类统一由公共依赖包管理，并剔除作用不大的组件，禁止微服务自定义配置。
>
> 包括全局异常、实体基类、上下文管理、MVC、Jackson、MybatisPlus、OpenApi、Redis等。

## 4.2 统一配置管理（配置分级）

**`面临的问题：`**

* 配置中心大量重复配置
* 配置中心存在大量不一致的配置

**`配置分级:`**

* 核心配置通过启动参数控制

* 基础配置在代码配置文件中

* 业务配置保存在数据库中

  > 例：网关白名单使用单独的表保存

## 4.3 统一返回格式

**`当前坏味道：`**

* 存在多套返回格式，废弃的格式未完全删除，存在大量遗留代码。
* 推荐的返回格式可读性和易用性差，对接口文档的支持不好。
* 自义定错误码不成体系，与标准错误码即存在冲突也存在冗余。

> 参考 Response

## 4.4 统一查询格式

**`当前坏味道`**

* 存在大量和Po存在重复的Dto、QueryParam、QueryForm、Vo用于查询参数定义，霰弹式修改。
* 存在大量查询参数写死的接口，变化方向没有分离，可扩展性差。
* 存在大量功能相似的查询相关代码，比如RequestParam -> Dto -> QueryWrapper。

**`应对方案`**

* 统一查询格式

  > 预留关键字：current、size、orders、search、fields、equals、likes、betweens、ins、groups
  >
  > 分页：current、size（省略表示查询全量）
  >
  > 精准查询：即传统查询 ?field=value&...。
  >
  > 自定义排序：?`orders`=k1,-k2,k3
  >
  > 模糊查询：?field~=like
  >
  > 范围查询：?field<=begin&field>=end
  >
  > in语法：?field=v1&field=v2
  >
  > 智能查询：?`search`=likes
  >
  > 字段投影：fields（保留）
  >
  > 分组聚合：groups（保留）

* 提炼 QueryWrapperBuilder
* 自适应的多表关联查询语句

## 4.5 统一接口约束

**`当前坏味道：`**

> 更多接口参考能装资源管理

* /menu/parent/{id}
* /menu/getAllMenu：POST
* /menu/getmymenu/{userid}
* /menu/getRolemenu/{roleid}
* /position/all
* /resource/conditions：POST
* /resource/batch
* /resource/allgroup
* /role/action/{id}
* /user/queryFromCache
* /user/addWithReturn

1. 常见（简单）接口

   > 单数还是复数，动作还是方法

   * 分页/列表接口：**`GET /resources`**  (不推荐：/resources + page、list、pagedList、all、noPage）
   * 详情接口：**`GET /resources/{id}`**  （不推荐：/resources/detail/{id}）
   * 新增接口：**`POST /resources`**  (不推荐：/resources/add）
   * 编辑接口：**`PUT /resources/{id}`** (不推荐：/resources/update）
   * 删除接口：**`DELETE /resources/{id}`** (不推荐：/resources/delete）

2. 新增 & 编辑接口怎么办 ？

   > 约束：路径不能带{id}（id可能没有）

   * 选项一：/resources/saveorupdate ：打破原则（使用HTTP方法来表达动作）。
   * 选项二：POST /resources ：腐化了前面的简单接口，职责不单一
   * 选项三：**`PUT /resources`** ：暂定

3. 批量删除接口怎么办 ？

   > DELETE or PUT or 回归以前的单一GET和POST ? 

   * 选项一：DELETE /resources/{ids} ： 和删除接口重复，侵入简单接口
   * 选项二：DELETE /resources/batch/{ids} or /resources/bulk/{ids} ：  存在特殊意义的语义
   * 选项三：**`DELETE /resources`** ： 请求传body，兼容性问题 ？

4. 批量新增接口怎么办 ？

   > 新增首先想到 POST。

   * 选项一：POST /resources  ： 和单一接口冲突
   * 选项二：POST /resources/bulk or /resources/batch  ：

   > 能不能使用 PUT ?

   * 选项一：**`PUT /resources`** ：  和新增 & 编辑接口冲突 ?
   * 选项二：PUT /resources /bulk ： 不如 POST /resources/bulk

5. 特殊接口怎么办 ?

   > 审核、驳回、预约、叫号.......，POST or PUT，是新增还是编辑 ？

   * 选项一：PUT /resources/approval or check or audit or review ?
   * 选项二：PUT /resources/call
   * 选项三：PUT /resources/reject
   * 选项四：PUT /resources/next ? 下一步
   * 选项五：**`PUT /resources/{field}`** -> PUT /resources/state
   * 选项六：PUT /resources/{id}/{field}

6. 结束了 ？

   > 小红点统计怎么处理 ？

   * 选项一：GET /resources/statistics ：有没有必要扩展统计字段 ？
   * 选项二：分组聚合 ：URL怎么表达 ？

   > 子表关系如何表达 ？

   * 选项一：/resources/{id}/relations  ？批量接口如何定义 ?
   * 选项二：**`/resources/relations`**  ？回归特殊接口，异曲同工

**`总结`**

* 一类资源两个URL：资源集合（resources）和资源元素（resources/{id}）

  > 批量查询：GET /resources
  >
  > 批量新增/编辑：PUT /resources
  >
  > 批量删除：DELETE /resources
  >
  > 新增：**`POST /resources`** ：特殊？习惯？单数resource？统一？
  >
  > 详情：GET /resources/{id}
  >
  > 编辑：PUT /resources/{id}
  >
  > 删除：DELETE /resources/{id}

* 一致的复数名词：避免混用复数和单数形式

* 使用名词而不是动词：使用HTTP方法来表达动作（增、删、改、查）

  > 特殊操作：PUT /resources/{field}
  >

* 对可选及复杂参数使用查询字符串（？）：保持URL简单短小

# 5. 数据驱动开发

## 5.1 数据模型定义

* 单表结构

  ![image-20220301161823742](https://gitee.com/emoxi/drawing-bed/raw/master/images/image-20220301161823742.png)

* 多对一结构

  ![image-20220301162018002](https://gitee.com/emoxi/drawing-bed/raw/master/images/image-20220301162018002.png)

  > 既要保存 Id，也要保存其他属性？

* 多对多结构

  ![image-20220302102040252](https://gitee.com/emoxi/drawing-bed/raw/master/images/image-20220302102040252.png)

  > 多对多使用关联表 还是 JSON？

## 5.2 元数据定义

```xml
<table name="数据库表名（使用数据库命名规则），一般使用复数"
       alias="表别名，用于uri和包名（默认等于数据库表名）"
       singular="表名对应的单数形式，用于类名、变量名"
       desc="描述，用于数据库COMMENT和接口文档"
       traceable="是否需要操作日志（默认false）（待定）"
       orders="默认排序字段（多个字段使用逗号分隔，降序在字符名前添加减号）">
    <field name="字段名"
           type="字段类型，参考 SchemaType"
           not-null="是否非空"
           default="默认值"
           visible="列表是否显示（当前无用）"
           searchable="是否参与智能搜索"
           format="格式化参数"
           unmodifiable="是否不可编辑"
           unique="是否唯一"
           desc="描述"/>
    <foreign key="字段名"
             references="引用外键：表名(列名)"
             not-null="是否非空"
             desc="描述"
             visible="列表是否显示"
             hidden="详情是否隐藏"
             constrained="是否创建外键约束"/>
    <relation to="子表"
              desc="描述"
              hidden="详情是否隐藏"
              constrained="是否创建外键约束">
        <field/>
    </relation>
</table>
```

## 5.3 代码生成器（编译插件）

1. 自定义 maven 编译插件

   > 参考 alpha-build-plugin

2. 微服务 parent pom 引入插件

```xml
<plugin>
    <groupId>cloud.alpha</groupId>
    <artifactId>alpha-build-plugin</artifactId>
    <version>${alpha-cloud.version}</version>
    <executions>
        <execution>
            <phase>initialize</phase>
            <goals>
                <goal>alpha-build</goal>
            </goals>
        </execution>
    </executions>
</plugin>
```

3. 编译自动生成基础代码

   > 工具自动生成代码，禁止修改，再次编译后自动覆盖

   **`生成代码包括：`**

   * 实体类（基础表、关联表）：表字段、接口文档、parent/children（可选）、外键对象、关联对象
   * Repository（基础表、关联表）：**自适应的多表关联查询语句**
   * Service（基础表、关联表）：
   * Mappings（主表和子表）：**统一查询参数**

## 5.4 数据库自管理

1. SchemaInitializer 负责服务启动时，读取元数据，自动创建或更新表结构

   > 只会添加表和字段，不会删除表或字段

2. _schemas_details 保存每张表最新的元数据详情，逻辑删除保证可跟踪

   ![image-20220301172155800](https://gitee.com/emoxi/drawing-bed/raw/master/images/image-20220301172155800.png)

3. _schemas_logs 记录每一次数据库变创建或更新语句

   ![image-20220302170704973](https://gitee.com/emoxi/drawing-bed/raw/master/images/image-20220302170704973.png)

# 6. 规范化开发

## 7.1 工欲善其事必先利其器

* IDEA 安装 Alibaba Java Coding Guidelines 插件
* IDEA 安装 SonarLint 插件

## 7.2 云效门禁

* 云效门禁强制开启
* 模块 owner 负责代码 review

## 7.3 运维管理

* 工程化微服务部署相关脚本和配置
* 工程化运维工具相关脚本和配置
* 前端添加运维管理功能

# 7. 改进的 RBAC

**`面临的问题:`**

* 按钮级权限控制不支持，扩展成本大。
* 小程序权限控制不支持，扩展成本大。
* 资源管理复杂，字段冗余。
* 功能角色定义没有标准，粒度无法控制
* 岗位配置不够灵活。

> 所见即所得

**`改进后方案`**

![image-20220301180321514](https://gitee.com/emoxi/drawing-bed/raw/master/images/image-20220301180321514.png)

* 权限只需配置请求地址、请求方法基础的属性。
* 菜单配置到按钮级（可以包含PC端和小程序），菜单、资源、菜单与资源的对应关系由开发配置。
* 用户组充当传统模式下的角色（比如管理员、司机等）。
* 利用岗位和组织的树形关系实现菜单（权限）的继承，组织和岗位可以使用同一张表。

# 8. 高性能 REST 鉴权匹配

> 基于改进的字典树实现高性能URL匹配

```mermaid
graph LR
	root==>user
	root==>common
	common==>logs==>get==>r1([admin])
	user==>api==>*==>post==>x([user,admin])
```

| 模式    | 描述                         | 备注     |
| ------- | ---------------------------- | -------- |
| str*str | 字符串中*匹配0个或者多个字符 | 无需支持 |
| /*/     | 匹配1个目录                  | 需支持   |
| **      | 匹配0个或多个目录            | 无需支持 |

# 9. 其他功能

## 定时任务

> 定时任务统一配置到公共基础服务，根据任务周期定时调用配置的微服务REST地址。 -- 待定

## OSS

## OCR

## SMS

## 操作日志

> 根据元数据处理操作日志的数据映射。 -- 待定

## 导入导出

## 报表统计