385 lines
11 KiB
Markdown
385 lines
11 KiB
Markdown
# 开发文档目录
|
||
|
||
## 目录说明
|
||
|
||
此目录用于存放项目的开发相关文档，包括开发指南、代码样例、问题记录等。
|
||
|
||
## 1. 开发环境搭建
|
||
|
||
### 环境准备
|
||
|
||
- **开发环境搭建指南.md**：完整的开发环境搭建步骤
|
||
- **IDE 配置指南.md**：IntelliJ IDEA 开发环境配置
|
||
- **Maven 配置.md**：Maven 环境配置和私服配置
|
||
- **Git 配置.md**：Git 版本控制配置
|
||
|
||
### 工具安装
|
||
|
||
- **JDK 安装配置.md**：Java 开发环境安装
|
||
- **Node.js 安装配置.md**：前端开发环境安装
|
||
- **数据库安装.md**：MySQL 和 Redis 安装配置
|
||
- **开发工具推荐.md**：推荐的开发工具和插件
|
||
|
||
### 环境配置示例：
|
||
|
||
```bash
|
||
# 开发环境启动脚本示例
|
||
#!/bin/bash
|
||
|
||
# 启动MySQL
|
||
sudo systemctl start mysql
|
||
|
||
# 启动Redis
|
||
sudo systemctl start redis
|
||
|
||
# 启动后端应用
|
||
cd ruoyi-admin
|
||
mvn spring-boot:run -Dspring-boot.run.profiles=dev
|
||
|
||
# 启动前端应用
|
||
cd ../plus-ui
|
||
npm run dev
|
||
```
|
||
|
||
## 2. 开发规范和指南
|
||
|
||
### 代码规范
|
||
|
||
- **Java 代码规范.md**：Java 代码编写规范
|
||
- **前端代码规范.md**：Vue3+TypeScript 代码规范
|
||
- **数据库设计规范.md**：数据库表设计规范
|
||
- **API 接口规范.md**：RESTful API 设计规范
|
||
|
||
### 命名规范
|
||
|
||
- **包命名规范.md**：Java 包命名规范
|
||
- **类和方法命名.md**：类和方法命名规范
|
||
- **数据库命名规范.md**：表和字段命名规范
|
||
- **前端命名规范.md**：组件和方法命名规范
|
||
|
||
### Git 规范
|
||
|
||
- **Git 分支规范.md**：Git 分支管理规范
|
||
- **提交信息规范.md**：Git 提交信息格式规范
|
||
- **代码审查流程.md**：Code Review 流程和标准
|
||
|
||
## 3. 架构设计指南
|
||
|
||
### 系统架构
|
||
|
||
- **整体架构设计.md**：系统整体架构设计说明
|
||
- **模块化设计.md**：模块化架构设计原则
|
||
- **分层架构设计.md**：分层架构设计和职责划分
|
||
- **微服务架构.md**：微服务架构设计指南
|
||
|
||
### 设计模式
|
||
|
||
- **常用设计模式.md**：项目中使用的设计模式
|
||
- **Spring 设计模式.md**：Spring 框架中的设计模式
|
||
- **业务设计模式.md**：业务层常用设计模式
|
||
|
||
### 架构示例：
|
||
|
||
```java
|
||
// 标准Controller示例
|
||
@RestController
|
||
@RequestMapping("/api/v1/users")
|
||
@Tag(name = "用户管理", description = "用户管理相关接口")
|
||
public class UserController extends BaseController {
|
||
|
||
@Autowired
|
||
private IUserService userService;
|
||
|
||
@SaCheckPermission("system:user:list")
|
||
@GetMapping
|
||
@Operation(summary = "查询用户列表", description = "分页查询用户信息")
|
||
public R<PageResult<UserVO>> list(@Valid UserQueryDTO queryDTO) {
|
||
return R.ok(userService.queryPageList(queryDTO));
|
||
}
|
||
}
|
||
```
|
||
|
||
## 4. 功能开发指南
|
||
|
||
### 新功能开发流程
|
||
|
||
- **功能开发流程.md**：从需求到上线的完整流程
|
||
- **业务模块开发.md**：新业务模块开发步骤
|
||
- **接口开发指南.md**：API 接口开发步骤
|
||
- **前端页面开发.md**：前端页面开发步骤
|
||
|
||
### 数据库开发
|
||
|
||
- **数据库设计流程.md**：数据库表设计流程
|
||
- **SQL 编写规范.md**：SQL 语句编写规范
|
||
- **数据迁移指南.md**：数据库迁移指南
|
||
- **性能优化指南.md**：SQL 性能优化指南
|
||
|
||
### 缓存开发
|
||
|
||
- **Redis 使用指南.md**：Redis 缓存使用指南
|
||
- **缓存策略设计.md**：缓存策略设计原则
|
||
- **分布式锁使用.md**：分布式锁使用指南
|
||
|
||
## 5. 代码样例和模板
|
||
|
||
### 后端代码模板
|
||
|
||
- **Controller 模板.md**：标准 Controller 代码模板
|
||
- **Service 模板.md**：标准 Service 代码模板
|
||
- **Mapper 模板.md**：标准 Mapper 代码模板
|
||
- **Entity 模板.md**：标准实体类代码模板
|
||
|
||
### 前端代码模板
|
||
|
||
- **Vue 组件模板.md**：标准 Vue 组件模板
|
||
- **API 调用模板.md**：API 接口调用模板
|
||
- **表单组件模板.md**：表单组件开发模板
|
||
- **表格组件模板.md**：表格组件开发模板
|
||
|
||
### 配置文件模板
|
||
|
||
- **application.yml 模板.md**：应用配置模板
|
||
- **logback 配置模板.md**：日志配置模板
|
||
- **Dockerfile 模板.md**：Docker 镜像构建模板
|
||
|
||
### Service 层代码示例：
|
||
|
||
```java
|
||
@Service
|
||
@Transactional(rollbackFor = Exception.class)
|
||
public class UserServiceImpl implements IUserService {
|
||
|
||
@Autowired
|
||
private UserMapper userMapper;
|
||
|
||
@Override
|
||
@DataPermission(deptAlias = "d", userAlias = "u")
|
||
public PageResult<UserVO> queryPageList(UserQueryDTO queryDTO) {
|
||
LambdaQueryWrapper<SysUser> lqw = buildQueryWrapper(queryDTO);
|
||
Page<UserVO> result = userMapper.selectVoPage(queryDTO.toPage(), lqw);
|
||
return PageResult.build(result);
|
||
}
|
||
|
||
private LambdaQueryWrapper<SysUser> buildQueryWrapper(UserQueryDTO queryDTO) {
|
||
return Wrappers.<SysUser>lambdaQuery()
|
||
.like(StringUtils.isNotBlank(queryDTO.getUserName()),
|
||
SysUser::getUserName, queryDTO.getUserName())
|
||
.eq(StringUtils.isNotBlank(queryDTO.getStatus()),
|
||
SysUser::getStatus, queryDTO.getStatus())
|
||
.between(queryDTO.getCreateTime() != null && queryDTO.getCreateTime().length == 2,
|
||
SysUser::getCreateTime,
|
||
queryDTO.getCreateTime()[0], queryDTO.getCreateTime()[1]);
|
||
}
|
||
}
|
||
```
|
||
|
||
## 6. 第三方集成指南
|
||
|
||
### 权限认证集成
|
||
|
||
- **Sa-Token 集成.md**：Sa-Token 权限框架集成
|
||
- **JWT 配置.md**：JWT 令牌配置和使用
|
||
- **第三方登录.md**：第三方登录集成指南
|
||
- **单点登录.md**：SSO 单点登录配置
|
||
|
||
### 消息服务集成
|
||
|
||
- **短信服务集成.md**：短信服务集成指南
|
||
- **邮件服务集成.md**：邮件服务集成指南
|
||
- **消息中间件.md**：消息队列集成指南
|
||
|
||
### 存储服务集成
|
||
|
||
- **文件存储集成.md**：MinIO 文件存储集成
|
||
- **云存储集成.md**：阿里云 OSS 等云存储集成
|
||
- **图片处理.md**：图片上传和处理
|
||
|
||
## 7. 测试开发指南
|
||
|
||
### 单元测试
|
||
|
||
- **单元测试编写.md**：单元测试编写指南
|
||
- **Mock 测试.md**：Mock 对象使用指南
|
||
- **测试用例设计.md**：测试用例设计原则
|
||
- **测试覆盖率.md**：测试覆盖率要求和检查
|
||
|
||
### 集成测试
|
||
|
||
- **集成测试编写.md**：集成测试编写指南
|
||
- **数据库测试.md**：数据库操作测试
|
||
- **API 测试.md**：API 接口测试
|
||
|
||
### 测试示例：
|
||
|
||
```java
|
||
@SpringBootTest
|
||
@Transactional
|
||
@Rollback
|
||
class UserServiceTest {
|
||
|
||
@Autowired
|
||
private IUserService userService;
|
||
|
||
@Test
|
||
@DisplayName("测试用户查询功能")
|
||
void testQueryUser() {
|
||
// Given
|
||
UserQueryDTO queryDTO = new UserQueryDTO();
|
||
queryDTO.setUserName("admin");
|
||
|
||
// When
|
||
PageResult<UserVO> result = userService.queryPageList(queryDTO);
|
||
|
||
// Then
|
||
assertThat(result).isNotNull();
|
||
assertThat(result.getRecords()).isNotEmpty();
|
||
}
|
||
}
|
||
```
|
||
|
||
## 8. 性能优化指南
|
||
|
||
### 代码优化
|
||
|
||
- **算法优化.md**：常见算法优化技巧
|
||
- **集合框架优化.md**：Java 集合使用优化
|
||
- **字符串优化.md**：字符串操作优化
|
||
- **反射优化.md**：反射操作优化
|
||
|
||
### 数据库优化
|
||
|
||
- **查询优化.md**：SQL 查询优化指南
|
||
- **索引优化.md**：数据库索引优化
|
||
- **连接池优化.md**：数据库连接池优化
|
||
- **分页优化.md**：大数据量分页优化
|
||
|
||
### 缓存优化
|
||
|
||
- **缓存设计.md**：缓存设计最佳实践
|
||
- **缓存穿透.md**：缓存穿透问题解决
|
||
- **缓存雪崩.md**：缓存雪崩问题解决
|
||
- **缓存击穿.md**：缓存击穿问题解决
|
||
|
||
## 9. 问题记录和解决方案
|
||
|
||
### 常见问题
|
||
|
||
- **启动问题.md**：应用启动常见问题
|
||
- **配置问题.md**：配置相关常见问题
|
||
- **数据库问题.md**：数据库连接和操作问题
|
||
- **缓存问题.md**：Redis 缓存相关问题
|
||
|
||
### 框架问题
|
||
|
||
- **Spring Boot 问题.md**：Spring Boot 框架问题
|
||
- **MyBatis Plus 问题.md**：MyBatis Plus 相关问题
|
||
- **Sa-Token 问题.md**：Sa-Token 权限框架问题
|
||
- **前端框架问题.md**：Vue3 相关问题
|
||
|
||
### 部署问题
|
||
|
||
- **Docker 问题.md**：Docker 部署相关问题
|
||
- **Nginx 问题.md**：Nginx 配置相关问题
|
||
- **SSL 证书问题.md**：SSL 证书配置问题
|
||
|
||
## 10. 版本升级指南
|
||
|
||
### 框架升级
|
||
|
||
- **Spring Boot 升级.md**：Spring Boot 版本升级指南
|
||
- **Java 版本升级.md**：Java 版本升级指南
|
||
- **依赖升级.md**：第三方依赖升级指南
|
||
|
||
### 数据库升级
|
||
|
||
- **MySQL 升级.md**：MySQL 版本升级指南
|
||
- **Redis 升级.md**：Redis 版本升级指南
|
||
- **数据迁移.md**：数据库结构迁移指南
|
||
|
||
### 兼容性处理
|
||
|
||
- **向后兼容.md**：向后兼容性处理
|
||
- **接口兼容.md**：API 接口兼容性处理
|
||
- **数据兼容.md**：数据格式兼容性处理
|
||
|
||
## 11. 开发工具和插件
|
||
|
||
### IDEA 插件推荐
|
||
|
||
```
|
||
必装插件:
|
||
- Lombok
|
||
- MyBatis Plus
|
||
- Alibaba Java规约检查
|
||
- SonarLint
|
||
- GitToolBox
|
||
- Rainbow Brackets
|
||
- Translation
|
||
|
||
可选插件:
|
||
- JRebel (热部署)
|
||
- Sequence Diagram (时序图)
|
||
- RestfulTool (接口测试)
|
||
- Database Navigator (数据库)
|
||
```
|
||
|
||
### 开发工具推荐
|
||
|
||
- **数据库工具**: Navicat Premium / DataGrip
|
||
- **Redis 工具**: RedisDesktopManager / AnotherRedisDesktopManager
|
||
- **API 工具**: Postman / Insomnia
|
||
- **Git 工具**: SourceTree / GitKraken
|
||
- **文档工具**: Typora / Mark Text
|
||
|
||
### 代码质量工具
|
||
|
||
- **静态分析**: SonarQube
|
||
- **代码格式**: Google Java Format
|
||
- **依赖检查**: OWASP Dependency Check
|
||
- **测试覆盖**: JaCoCo
|
||
|
||
## 12. 快速开始
|
||
|
||
### 项目初始化
|
||
|
||
```bash
|
||
# 1. 克隆项目
|
||
git clone https://gitee.com/dromara/RuoYi-Vue-Plus.git
|
||
|
||
# 2. 导入数据库
|
||
mysql -u root -p < script/sql/ry_vue_5.X.sql
|
||
|
||
# 3. 修改配置
|
||
# 编辑 ruoyi-admin/src/main/resources/application-dev.yml
|
||
# 修改数据库连接信息
|
||
|
||
# 4. 启动后端
|
||
cd ruoyi-admin
|
||
mvn spring-boot:run
|
||
|
||
# 5. 启动前端
|
||
cd plus-ui
|
||
npm install
|
||
npm run dev
|
||
```
|
||
|
||
### 新模块开发步骤
|
||
|
||
1. **需求分析**: 明确功能需求和技术要求
|
||
2. **数据库设计**: 设计表结构和关系
|
||
3. **代码生成**: 使用代码生成器生成基础代码
|
||
4. **业务开发**: 实现具体业务逻辑
|
||
5. **前端开发**: 开发前端页面和交互
|
||
6. **测试验证**: 编写测试用例并验证
|
||
7. **文档更新**: 更新相关文档
|
||
|
||
## 注意事项
|
||
|
||
1. 开发前必须阅读框架文档和开发规范
|
||
2. 新功能开发需要编写对应的测试用例
|
||
3. 代码提交前需要通过代码规范检查
|
||
4. 重要功能变更需要进行 Code Review
|
||
5. 及时更新开发文档和接口文档
|
||
6. 遵循安全编码规范，避免安全漏洞
|