基础框架文档中心

外观

开始开发 ​

本篇对一般业务开发过程，以及各模块要注意的事项作出说明。

数据库 ​

经过业务需求分析后，我们首先会创建数据库表，这时需要遵循一定的规范。

注意

  • 表名需要以业务模块简称作为前缀，多个单词以下划线分隔。例如：sys_user_role。
  • 业务表需要继承 sys_base_table表，获得id、操作人、操作时间等基础字段。
  • 列名有多个单词时同样以下划线分隔。例如：role_name。
  • 列必须添加注释内容。
  • 表必须添加主键，主键列为 id。
  • 根据实际情况，为查询关键列建立索引。

提示

完整规范内容请查看数据库规范。

生成代码 ​

创建数据库之后，就可以使用 IDEA 的插件 mybatisx 生成基础代码—— entity、mapper、service。

  1. 首先打开 idea 的数据库视图，添加数据库连接后可以看到数据表。

    gen

  2. 在要生成代码的表上点右键，选择“MybatisX-Generator”进入生成配置。注意base package与 relative package设置。

    gen

  3. 下一步按下图所示选择，确认生成即可。

    gen

注意

  • 生成的代码文件需要根据项目结构放入正确的位置。
  • 生成的 entity 类默认包含 id、操作人、操作时间字段，需要删除并修改为从com.hzcc.model.entity.BaseEntity继承。

Model ​

model 模块用于放置各种业务模型类。除了生成的实体类之外，通常还需要编写入参类、出参类、枚举类等。 需要将类按用途放入不同的包，规则与框架一致：

  • 入参 input
  • 出参 output
  • 表实体 entity
  • 网络请求 remote
  • 中间类 inter

注意

  • 命名规则：入参以Dto结尾、出参以Vo结尾，实体类与表名一致（不包含统一前缀）
  • 简单参数验证需要在入参类通过 Hibernate Validator 相关注解进行。
  • 模型类的属性必须添加注释，特殊取值需要在注释中注明。
  • 入参、出参类的属性必须添加 Swaager 文档注解：@ApiModel、@ApiModelProperty
  • 如果要控制出参序列化结果，需要使用 jackson 相关注解，不使用fastjson。

提示

更多 Model 命名规范请查看代码规范。

Mapper ​

使用 mybatis-plus 或 mybatis-plus-join 内置的方法可以实现大部分数据库操作，因此 mapper 层的代码一般会很少， 直接使用生成的代码即可。

注意

  • 生成的代码默认继承BaseMapper接口，如果要使用关联查询方法，请修改为继承MPJBaseMapper。
  • 如果某些数据操作较为复杂，使用ORM实现困难，可以直接编写 sql 实现，同时需要在 readme.md 说明。

Service ​

服务层是整个项目的核心层，在这里实现业务逻辑。通过继承基础服务类即可获得基本的数据库操作功能。

简单示例如下：

java
@Service
public class RoleServiceImpl extends ServiceImpl<RoleMapper, Role> implements RoleService
{
    /**
     * 查询角色名
     *
     * @param id 用户编号
     */
    public String getRoleName(String id)
    {
        Role role = getOne(new LambdaQueryWrapper<Role>()
            .select(Role::getName)
            .eq(Role::getId, input.getId())
        );
        return role == null ? null : role.getName();
    }
}
java
public interface RoleService extends IService<Role>
{
    /**
     * 查询角色名
     *
     * @param id 用户编号
     */
    String getRoleName(String id);
}

注意

  • 需要编写服务接口与实现类，实现类需放入子包impl中。
  • 如果业务具有明显的独立模块且每个模块包含大量类，可以以模块简称建立包，再编写服务接口与实现类。
  • 生成的代码默认继承 IService、ServiceImpl，如果要使用关联查询方法请修改为 MPJBaseService、MPJBaseServiceImpl。
  • 数据库列通过方法引用形式指定，一般场景禁止使用字符串形式。
  • 优先使用接收LambdaQueryWrapper、LambdaUpdateWrapper参数的重载方法进行数据库操作。
  • 非必要禁止查询所有字段，按实际需要指定查询列。
  • 接口方法必须添加注释，入参必须添加说明，返回值按需说明。
  • 如果需要抛出业务异常，统一使用 ServiceException。
  • 根据实际情况使用@Transactional声明数据库事务。

提示

Service 模块命名规范请查看代码规范。

Api ​

在这里编写控制器类，定义访问路由、验证权限、调用相应的服务完成业务功能。

示例如下：

java
@Api(tags = "角色管理")
@RestController
@RequestMapping("/api/role")
public class RoleController {
    @Autowired
    RoleService service;

    /**
     * 查询
     */
    @ApiOperation("查询")
    @PreAuthorize("@ss.hasPermi('roles:list')")
    @GetMapping("/list")
    public AjaxResult<PageVo<Role>> list(RoleSearchInput input, PageInfo page) {
        PageVo<Role> list = service.search(input, page);
        return AjaxResult.success(list);
    }
}

注意

  • 除特殊情况（如下载文件）外，控制器方法统一返回 AjaxResult 对象，且尽可能使用泛型类声明返回类型。
  • 权限验证使用 @PreAuthorize 调用PermissionExaminator（声明为ss）中的验证方法，具体权限标识为系统菜单中“按钮类型”菜单项的 url 字段。
  • 控制器类和方法必须添加 Swagger 文档声明： @Api、@ApiOperation。
  • 接口访问路径需要遵循 restful 规范。
  • 控制器方法一般情况下禁止编写复杂业务逻辑。
  • 接收 2 个以上参数时应使用模型类接收。
  • 分页参数使用独立的 PageInfo 类。
  • JSON 消息转换器实现使用默认的Jackson实现。
  • 如果需要记录关键操作日志，请使用 @Log 注解。
  • 如果要手动抛出异常，统一使用 ServiceException。

提示

请求响应相关规范请查看代码规范。