# quick-start

**Repository Path**: handuan-cloud/quick-start

## Basic Information

- **Project Name**: quick-start
- **Description**: handuan cloud quick start
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-06-05
- **Last Updated**: 2024-06-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Quick Start

## 相关文档

- [基础服务安装](docs/core-services.md)

## 后端开发入门

### 工具

| 类型   | 工具名称        | 下载地址                                          |
|------|-------------|-----------------------------------------------|
| 版本控制 | git         | /                                             |
| IDE  | idea        | https://www.jetbrains.com/zh-cn/idea/download |
| 数据建模 | pdManer     | http://www.pdmaner.com/download/v4.9.0        |
| 工具   | SwitchHosts | https://github.com/oldj/SwitchHosts/releases  |
|      |             |                                               |

#### SwitchHosts

> 方便进行hosts切换，hosts权限设置，请参考以下文档：

- https://blog.csdn.net/aiains/article/details/139218503

### 框架及版本

| 类型    | 框架               | 版本号        | 说明               |
|-------|------------------|------------|------------------|
| 基础框架  | openJDK          | 17         |                  |
| 基础框架  | spring-boot      | 3.2.6      |                  |
| 基础框架  | spring-cloud     | 2023.0.1   |                  |
| 基础框架  | alibaba-cloud    | 2023.0.1.0 |                  |
| 基础框架  | springdoc        | 2.5.0      |                  |
| 基础框架  | querydsl         | 5.1.0      | 查询构造             |
| 基础框架  | lombok           | 1.18.22    |                  |
| 基础框架  | mapstruct        | 1.5.0.RC1  | 各种实体转换，bean copy |
| 基础框架  | hutool           | 5.8.27     | 工具类汇总            |
| 自定义框架 | handuanframework | 3.2.5.4    | 基础框架封装           |
| 自定义框架 | handuan-cloud    | 3.2.5.1    | 基础模块实现封装         |

### 包结构说明

> 请见 samples/core

![](docs/services/package-sample.png)

- web API 请求入口
- service 逻辑层及实现类
- model 模型层，包括：DTO、SaveModel、SearchParam 等
- entity 实体层及实体对应的 Repo
- converter 转换层，实体、模型间转换

### 代码生成器

- 使用 pdManer 设计数据表，并按需指定字段相关用途 ![](docs/services/codegen_01.png)
- 设置实体路径及变量 ![](docs/services/codegen_02.png)
- 引用已经设计好的实体（按需）![](docs/services/codegen_03.png)
- 生成代码 ![](docs/services/codegen_04.png)

### 数据库设计

- 支持数据库模版：**MySQL**及**DM**；
- 数据库设计时，表名和字段名，均小写，多个单词以下划线区分；
- 在生成实际数据库脚本时，系统会自动按需调整脚本的大小写规则（例如：MySQL 小写，DM 大写）；

#### 数据表设计

- 表名规则：通用前缀\_名称，小写；
- 创建新的数据表时，系统会自动生成默认字段，请根据需求进行删减；
- 如需要调整默认字段，请在设置的缺省字段设置中调整；
- 数据字段可以按需选择字段设置，代码生成器会根据字段的设置生成相应的代码

#### 数据字典设计

- 当数据库对应字段为数据字典时，数据域选择“数据字典”，同时新增或选择现有的数据字典
- 数据字典字段说明 ![](docs/services/codegen_05.png)

### 命名规范

> **所有数据库的结构性调整，必须在 pdManer 中进行设置！**

#### 数据库命名

- 表名：通用前缀\_名称，均小写，例如：sys_user；
- 字段名：小写，多个单词以下划线分隔，例如：user_name；
- 索引：idx\_索引名称，小写，例如：idx_login_id；

#### 代码命名

- 实体名称：数据库表名去掉前缀\_，例如：User；
- 其他常用 bean 对象命名：XxxDTO、XxxSaveModel、SxxSearchParam

#### 接口规范

- controller 入口请求均为主题域对象全小写+s，例如 user，接口地址为: /users
- 接口命名遵循 restfull 命名规则，例如
  - 新增用户: POST /users
  - 更新用户: PUT /users
  - 删除用户: DELETE /users/{id}
  - 查询用户列表：GET /users
  - 查询用户详情: GET /users/{id}

### 开发场景

#### 单元测试

- 相关依赖，参见 samples/junit-test/pom.xml
  ```xml
  <!--单元测试-->
  <dependency>
      <groupId>com.handuanframework</groupId>
      <artifactId>handuan-boot-starter-test</artifactId>
      <scope>test</scope>
  </dependency>
  <dependency>
      <artifactId>h2</artifactId>
      <groupId>com.h2database</groupId>
      <scope>test</scope>
  </dependency>
  ```
- 单元测试写法与 springBoot 保持一致，请参阅官方文档，示例代码：samples/junit-test/src/test/java/com/samples/crud/T01BasicCrudTest.java

#### 多表联查

- samples/junit-test/src/test/java/com/samples/crud/T02MultiEntitiesQueryTest.java
- samples/core/src/main/java/com/samples/service/impl/DeptServiceImpl.java

## 前端开发入门

### 前端依赖框架与组件

- Vue3 使用文档
  https://cn.vuejs.org/guide/quick-start.html

- Element-Plus 使用文档
  https://element-plus.org/zh-CN/component/tree.html

### 安装 nodejs

#### 下载

- 版本要求 18+
  ![alt text](docs/web/image.png)
- 下载地址：https://nodejs.org/en/download/prebuilt-installer

#### 安装完成测试

- 终端查看 node 版本

```
node -v
```

![alt text](docs/web/node-v.png)

- 终端查看 npm 版本

```
npm -v
```

![alt text](docs/web/npm-v.png)

### 开发环境启动

- 终端进入 web/目录下

```
cd web
```

![alt text](docs/web/cd-web.png)

- 在 web 目录下安装启动依赖

```
npm i
```

![alt text](docs/web/npm-i.png)

- 在 web 目录下启动环境

```
npm run dev
```

![alt text](docs/web/npm-run-dev.png)

- 默认情况下，会直接在浏览器中打开，如果没有打开，可以根据上一步骤中提示的启动服务 ip 和端口进行访问
- 账号 / 密码： admin / admin123
  ![alt text](docs/web/localhost-preview.png)

### 页面开发

#### 新增路由

- 在 web/src/router/index.js 中新增路由配置表
- 在 constantRoutes 变量下新增自己对应的路由表
  ![alt text](docs/web/constantRoutes.png)
- 新增路由表配置信息示例如下：

```
{
    name: 'test', // 路由名称
    path: 'test', // 路由路径，可以与name名称保持一致
    meta: {
        title: 'Test', // 菜单名称
        noCache: true,   // 固定属性值，就按照这个属性值配置
        icon: 'user',    // 菜单名称前的图标
    },
    hidden: false,       // 固定属性值，就按照这个属性值配置
    component: () => import('@/views/demo/test/index'), // 路由对应的显示组件地址，@表示web/src这一级目录。 加完这个配置，记得去component值对应的目录下新增index.vue文件
}
```

##### 新增页面

- 在 web/src/views 下新增路由表配置中 component 对应的地址文件
  ![alt text](docs/web/view.png)
- 在 index.vue 中编写 vue 单文件代码即可，示例如下：

```
<template>
  <div>测试文件</div>
</template>
<script>
export default {
  name: 'Test',
  props: {},
  components: {},
  data() {
    return {}
  },
  computed: {},
  watch: {},
  created() {},
  mounted() {},
  methods: {},
}
</script>
```

- 页面效果如下：
  ![alt text](docs/web/page-view.png)