SMF Core 开发指南

概述

本文档为SMF Core系统的开发人员提供指南，包含开发环境配置、代码规范、开发流程和最佳实践。

技术栈

• 后端框架: Spring Boot 2.x
• ORM框架: MyBatis-Plus, Spring Data MongoDB
• 数据库: MySQL 5.7+, MongoDB 4.0+
• 缓存: Redis 5.0+
• 消息队列: RabbitMQ (可选)
• API文档: Swagger 2.x
• 构建工具: Maven 3.6+
• 版本控制: Git

开发环境设置

1. IDE配置

推荐使用IntelliJ IDEA进行开发：

1. 安装插件:

   • Lombok
   • MyBatisX
   • Spring Assistant
   • SonarLint (代码质量检查)

2. 项目配置:

   • 导入为Maven项目
   • 配置JDK 1.8+作为项目SDK
   • 启用注解处理 (File → Settings → Build → Compiler → Annotation Processors)

2. 代码风格配置

使用项目提供的代码风格配置文件：

1. 在IntelliJ IDEA中导入代码风格：

   • File → Settings → Editor → Code Style
   • 点击右上角齿轮图标 → Import Scheme → IntelliJ IDEA code style XML
   • 选择 docs/codestyle/intellij-codestyle.xml

2. 配置检查规则：

   • File → Settings → Editor → Inspections
   • 导入 docs/codestyle/inspections.xml

代码架构

SMF Core采用分层架构设计：

com.neotel.smfcore/
├── integrations/    # 外部系统集成层
├── api-gateway/     # API网关层
├── business-services/ # 业务服务层
├── smf-platform/    # 平台核心层
└── shared/          # 共享组件层

详细架构说明请参考

开发规范

1. 包命名规范

com.neotel.smfcore.{layer}.{module}.{component}

示例：

// 业务服务层 - 订单模块 - 服务组件
com.neotel.smfcore.businessservices.order.service

2. 类命名规范

组件类型	命名规范	示例
接口	大驼峰，以I开头，以Service结尾	IOrderService
实现类	大驼峰，以Impl结尾	OrderServiceImpl
实体类	大驼峰，对应数据库表名	Order
DTO类	大驼峰，以DTO结尾	OrderDTO
控制器	大驼峰，以Controller结尾	OrderController
工具类	大驼峰，以Util结尾	DateUtil

3. 方法命名规范

操作类型	命名规范	示例
查询单个	getById, getOne	getOrderById(Long id)
查询列表	list, findAll	listOrders(OrderQuery query)
保存	save	saveOrder(Order order)
更新	update	updateOrder(Order order)
删除	deleteById	deleteOrderById(Long id)
批量操作	batch + 操作	batchSaveOrders(List<Order> orders)

4. 注释规范

使用Javadoc风格注释：

/**
 * 获取订单详情
 * @param id 订单ID
 * @return 订单信息
 * @throws OrderNotFoundException 当订单不存在时抛出
 */
public Order getOrderById(Long id) throws OrderNotFoundException {
    // 实现代码
}

开发流程

1. 需求分析

1. 理解业务需求
2. 分析技术可行性
3. 识别潜在风险
4. 制定开发计划

2. 设计阶段

1. 接口设计:

   • 定义API接口规范
   • 设计请求/响应格式
   • 在Swagger中预览API

2. 数据库设计:

   • 设计表结构
   • 定义索引
   • 创建ER图

3. 编码阶段

遵循以下编码流程：

1. 创建实体类和Mapper接口
2. 实现业务服务层
3. 实现控制器层
4. 编写单元测试
5. 添加日志和异常处理

4. 测试

1. 单元测试:

   • 使用JUnit 5编写测试用例
   • 测试覆盖核心业务逻辑
   • 执行 mvn test 运行测试

2. 集成测试:

   • 测试服务间集成
   • 测试数据库操作

3. API测试:

   • 使用Swagger UI测试API
   • 验证响应格式和状态码

错误处理

1. 异常体系

系统使用统一的异常处理机制：

// 业务异常
throw new BusinessException(ErrorCode.ORDER_NOT_FOUND, "订单不存在");

// 参数校验异常
throw new ValidationException("物料编码不能为空");

2. 全局异常处理

@RestControllerAdvice
public class GlobalExceptionHandler {

    @ExceptionHandler(BusinessException.class)
    public ResponseEntity<ApiResponse<?>> handleBusinessException(BusinessException e) {
        return ResponseEntity.ok(
            ApiResponse.error(e.getErrorCode(), e.getMessage())
        );
    }

    // 其他异常处理...
}

日志记录

1. 日志使用规范

使用SLF4J作为日志门面：

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class OrderServiceImpl implements IOrderService {
    private static final Logger logger = LoggerFactory.getLogger(OrderServiceImpl.class);

    @Override
    public Order createOrder(Order order) {
        logger.info("创建订单，订单号: {}", order.getOrderNo());
        // 业务逻辑
        try {
            // 实现代码
        } catch (Exception e) {
            logger.error("创建订单失败，订单号: {}", order.getOrderNo(), e);
            throw e;
        }
        return order;
    }
}

2. 日志级别使用

级别	用途
ERROR	记录错误信息，影响系统正常运行
WARN	记录警告信息，可能导致问题
INFO	记录重要操作和业务流程
DEBUG	记录调试信息，开发环境使用
TRACE	记录详细跟踪信息，极少使用

API文档生成

系统使用Swagger自动生成API文档：

1. API注解使用

@RestController
@RequestMapping("/api/v1/materials")
@Api(tags = "物料管理")
public class MaterialController {

    @GetMapping
    @ApiOperation("查询物料列表")
    public ApiResponse<PageResult<MaterialDTO>> listMaterials(
            @ApiParam("物料编码") @RequestParam(required = false) String materialCode,
            @ApiParam("页码") @RequestParam(defaultValue = "1") Integer page,
            @ApiParam("每页数量") @RequestParam(defaultValue = "10") Integer size) {
        // 实现代码
    }
}

2. 访问API文档

启动系统后，访问：

http://localhost:8080/smf-core/swagger-ui.html

数据库操作

1. MySQL操作

使用MyBatis-Plus进行数据库操作：

@Service
public class OrderServiceImpl implements IOrderService {

    @Autowired
    private OrderMapper orderMapper;

    @Override
    public List<Order> listOrdersByStatus(String status) {
        QueryWrapper<Order> queryWrapper = new QueryWrapper<>();
        queryWrapper.eq("status", status);
        return orderMapper.selectList(queryWrapper);
    }
}

2. MongoDB操作

使用Spring Data MongoDB操作MongoDB：

@Service
public class LogServiceImpl implements ILogService {

    @Autowired
    private LogRepository logRepository;

    @Override
    public List<OperationLog> findLogsByUserId(String userId) {
        return logRepository.findByUserId(userId, 
            PageRequest.of(0, 10, Sort.by(Sort.Direction.DESC, "createdTime")));
    }
}

代码审查流程

1. 提交代码前检查

1. 执行静态代码分析：

   mvn clean install -DskipTests
   

2. 运行单元测试：

   mvn test
   

3. 检查代码覆盖率报告

2. Pull Request流程

1. 创建功能分支：

   git checkout -b feature/your-feature-name
   

2. 提交代码：

   git add .
   git commit -m "feat: 添加功能描述"
   git push origin feature/your-feature-name
   

3. 在代码托管平台创建Pull Request

4. 等待代码审查，修复反馈的问题

5. 合并Pull Request

常见开发模式

1. 事务管理

使用声明式事务：

@Service
public class OrderServiceImpl implements IOrderService {

    @Transactional(rollbackFor = Exception.class)
    @Override
    public void processOrder(Order order) {
        // 多个数据库操作，任一失败都会回滚
        orderMapper.insert(order);
        inventoryService.updateInventory(order.getItems());
        // 其他操作...
    }
}

2. 缓存使用

使用Spring Cache进行缓存管理：

@Service
@CacheConfig(cacheNames = "materialCache")
public class MaterialServiceImpl implements IMaterialService {

    @Cacheable(key = "#id")
    @Override
    public Material getMaterialById(Long id) {
        // 从数据库查询
        return materialMapper.selectById(id);
    }

    @CacheEvict(key = "#material.id")
    @Override
    public void updateMaterial(Material material) {
        materialMapper.updateById(material);
    }
}

开发工具使用

1. Maven命令

# 清理并编译
mvn clean compile

# 运行测试
mvn test

# 打包
mvn package

# 安装到本地仓库
mvn install

# 运行应用
mvn spring-boot:run

2. Git命令

# 克隆仓库
git clone [仓库地址]

# 查看状态
git status

# 添加文件
git add .

# 提交
git commit -m "提交信息"

# 推送
git push origin branch-name

# 拉取
git pull origin branch-name

最佳实践

1. 代码复用:

   • 抽取公共代码到工具类
   • 使用继承和组合减少重复代码

2. 性能优化:

   • 使用索引优化查询
   • 避免N+1查询问题
   • 合理使用缓存

3. 安全性:

   • 对敏感数据进行加密
   • 防止SQL注入和XSS攻击
   • 实现适当的权限控制

4. 可维护性:

   • 编写清晰的代码和注释
   • 使用设计模式解决常见问题
   • 保持组件职责单一

故障排除

1. 常见问题

问题	可能原因	解决方案
编译错误	依赖冲突	检查pom.xml中的依赖版本
运行时异常	配置错误	检查application.yml配置
数据库连接失败	数据库未启动或配置错误	检查数据库服务状态和连接参数
内存不足	JVM内存设置过小	增加JVM内存配置

2. 调试技巧

1. 在IDE中设置断点
2. 使用日志进行问题诊断
3. 检查应用启动日志
4. 使用Spring Boot Actuator监控应用状态