SMF Core 迁移指南

本文档提供了SMF Core框架版本升级的迁移指南，帮助开发者顺利完成从旧版本到新版本的过渡。

从0.1.0版本迁移到1.0.0版本

1. 依赖升级

Spring Boot版本升级

确保在pom.xml中更新Spring Boot版本：

<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.x</version> <!-- 或更新版本 -->
    <relativePath/>
</parent>

2. BaseMapper接口使用变更

方法命名调整

在1.0.0版本中，BaseMapper接口的方法名称更加规范化，请确保您的实现类正确实现了新的方法名称：

0.1.0版本（旧）:

public interface UserMapper {
    UserEntity dtoToEntity(UserDto dto);
    UserDto entityToDto(UserEntity entity);
    List<UserEntity> dtosToEntities(List<UserDto> dtos);
    List<UserDto> entitiesToDtos(List<UserEntity> entities);
}

1.0.0版本（新）:

public interface UserMapper extends BaseMapper<UserDto, UserEntity> {
    // 方法名称变为toEntity、toDto等
    // 实现BaseMapper接口中的所有方法
}

3. null参数处理

1.0.0版本修复了BaseMapper接口在处理null参数时的类型歧义问题。在调用接口方法传递null值时，建议添加明确的类型转换以避免潜在的问题：

// 推荐的方式
UserEntity entity = mapper.toEntity((UserDto) null);
UserDto dto = mapper.toDto((UserEntity) null);

4. 配置文件结构变更

配置文件smfcore.json的结构在1.0.0版本中更加规范化：

1.0.0版本配置文件示例:

{
  "database": {
    "mongo": {
      "uri": "mongodb://username:password@host:port/database",
      "connections": 20,
      "maxWaitTime": 15000
    }
  },
  "service": {
    "port": 8080,
    "contextPath": "/api"
  },
  "logging": {
    "level": "INFO",
    "file": "logs/smf-core.log"
  },
  "i18n": {
    "defaultLocale": "zh_CN",
    "supportedLocales": ["zh_CN", "en_US"]
  }
}

请根据上述格式调整您的配置文件。

5. 包结构变更

1.0.0版本调整了部分包结构，确保您的导入语句正确更新为新的包路径：

0.1.0版本（旧）:

import com.smf.core.dao.BaseDao;
import com.smf.core.mapper.ObjectMapper;

1.0.0版本（新）:

import com.smf.core.dao.AbstractBaseDao;
import com.smf.core.mapper.BaseMapper;

6. 异常处理方式变更

1.0.0版本实现了统一的异常处理机制，请使用新的异常类型：

// 使用新的异常类
throw new ServiceException("业务处理失败", ErrorCode.BUSINESS_ERROR);

7. 测试代码调整

BaseMapperTest类中修复了null参数处理，在您自己的测试类中也应做相应调整：

@Test
public void testToEntityWithNull() {
    assertNull(mapper.toEntity((TestDto) null));
}

迁移建议

1. 增量迁移：建议分模块、分批次进行迁移，而不是一次性迁移所有内容

2. 全面测试：每次迁移后进行全面的单元测试、集成测试和回归测试

3. 备份：在开始迁移前，确保对项目代码和配置文件进行完整备份

4. 查阅API文档：详细了解新版本中的API变更，避免使用已废弃的方法

迁移常见问题

编译错误：找不到方法或类

解决方法：检查包路径和方法名称是否已按新版本要求更新，确认导入语句正确。

运行时错误：类型转换异常

解决方法：特别注意null参数的处理，添加明确的类型转换。

配置无法加载

解决方法：检查配置文件结构是否符合新版本要求，确保所有必要的配置项都已正确设置。

---

如果在迁移过程中遇到其他问题，请参考项目文档或联系技术支持团队获取进一步帮助。

---

最后更新时间：2024年