01-快速开始¶

📄 创建: ZCode AI 2026-08-14 · 修改: JimWb 2026-08-14

https://doc.xpku.com/raw/tech/backend/bams-sdk/01-quick-start.md

本篇带你用最短时间集成 bams-sdk，跑通一个完整的 CRUD 接口。

1. 环境要求¶

项	要求
JDK	21+
Maven	3.6+
Spring Boot	2.x（由 bams-parent 管理）
数据库	MySQL（开发）/ 达梦 DM（生产）
Redis	必需（缓存/Session）

2. 引入依赖¶

2.1 继承父工程¶

业务应用的 pom.xml 继承 bams-parent：

<parent>
    <groupId>cn.cnbm.bams</groupId>
    <artifactId>bams-parent</artifactId>
    <version>2.0</version>
    <relativePath/>
</parent>

2.2 按需引入 SDK 模块¶

不需要全引，按功能需要引入对应模块。模块间有依赖关系，Maven 会自动传递。

<dependencies>
    <!-- 核心三件套：CRUD 必需 -->
    <dependency>
        <groupId>cn.cnbm.bams</groupId>
        <artifactId>common-tool</artifactId>
        <version>2.0</version>
    </dependency>
    <dependency>
        <groupId>cn.cnbm.bams</groupId>
        <artifactId>bams-pojo</artifactId>
        <version>2.0</version>
    </dependency>
    <dependency>
        <groupId>cn.cnbm.bams</groupId>
        <artifactId>bams-service</artifactId>
        <version>2.0</version>
    </dependency>

    <!-- 通用功能：Controller 基类、异常处理、Swagger（强烈推荐） -->
    <dependency>
        <groupId>cn.cnbm.bams</groupId>
        <artifactId>common-func</artifactId>
        <version>2.0</version>
    </dependency>

    <!-- 数据权限（需要按公司/部门过滤数据时引入） -->
    <dependency>
        <groupId>cn.cnbm.bams</groupId>
        <artifactId>common-permission</artifactId>
        <version>2.0</version>
    </dependency>

    <!-- 文件管理 -->
    <dependency>
        <groupId>cn.cnbm.bams</groupId>
        <artifactId>bams-file</artifactId>
        <version>2.0</version>
    </dependency>

    <!-- 缓存 -->
    <dependency>
        <groupId>cn.cnbm.bams</groupId>
        <artifactId>common-cache</artifactId>
        <version>2.0</version>
    </dependency>

    <!-- 流程引擎（审批流/规则编排） -->
    <dependency>
        <groupId>cn.cnbm.bams</groupId>
        <artifactId>bams-flow</artifactId>
        <version>2.0</version>
    </dependency>
</dependencies>

各模块的职责和依赖关系详见 02-模块依赖与架构。

3. 最小配置¶

application.yml 关键配置项：

server:
  port: 8080
  servlet:
    context-path: /api

spring:
  # 主数据源
  datasource:
    driver-class-name: com.mysql.cj.jdbc.Driver
    url: jdbc:mysql://127.0.0.1:3306/bams?useUnicode=true&characterEncoding=utf8
    username: root
    password: root
  # Redis
  data:
    redis:
      host: 127.0.0.1
      port: 6379
      password:
      database: 3
  # Jackson（common-func 的 MyWebMvcConfigurer 会自动配置 SNAKE_CASE + 时间格式）
  settings:
    enable-table-auto-creation: true  # 首次启动自动建表

# 数据权限（common-permission）
project:
  check-permission: true              # 开启数据权限
  dynamic:
    datasource:
      db-type: mysql                  # mysql 或 dm（达梦）
  exclude-tables: sys_user,sys_role   # 排除数据权限的表（逗号分隔）
  cache:
    init-cache: true                  # 启动时加载缓存

# Session 校验
spring:
  check-session:
    enabled: true                     # 开启 session 校验

# Kafka（如使用 bams-mq）
project:
  kafka:
    consumer-enabled: true            # 开启消费者
    send-topic: send-data             # 生产默认 topic
    receive-topic-pattern: bams_.*    # 消费 topic 正则

4. 启动类¶

package cn.cnbm.bams.demo;

import cn.cnbm.bams.permission.startup.EnableDataPermission;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
@EnableDataPermission  // 开启数据权限框架（可选，不需要权限可去掉）
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

5. HelloWorld：三行代码得全套 CRUD¶

bams-sdk 的 EnergyBaseController 封装了 20+ 个通用 REST 接口。继承它，你的 Controller 只需声明泛型类型。

5.1 定义实体¶

package cn.cnbm.bams.demo.pojo;

import cn.cnbm.bams.pojo.base.BaseEntity;
import com.baomidou.mybatisplus.annotation.TableName;
import lombok.Data;
import lombok.EqualsAndHashCode;

@Data
@EqualsAndHashCode(callSuper = true)  // 重要：callSuper=true 才能继承 BaseEntity 字段
@TableName("demo_product")
public class DemoProduct extends BaseEntity {
    private String productCode;   // 产品编码
    private String productName;   // 产品名称
    private String corpCode;      // 公司编码（数据权限依赖此字段）
}

BaseEntity 已包含 id / createdBy / createdTime / updatedBy / updatedTime 字段，且 id 会在插入时由 IDUtil.getId()（雪花算法）自动生成。详见 04-实体与数据访问。

5.2 定义 Mapper¶

package cn.cnbm.bams.demo.mapper;

import cn.cnbm.bams.mapper.ext.BaseMapperExt;  // 注意：继承 BaseMapperExt 而非 BaseMapper
import cn.cnbm.bams.demo.pojo.DemoProduct;
import org.apache.ibatis.annotations.Mapper;

@Mapper
public interface DemoProductMapper extends BaseMapperExt<DemoProduct> {
}

BaseMapperExt 比 MyBatis-Plus 原生 BaseMapper 多 5 个方法（selectPageMaps 返回 Map 分页 + 4 个原生 SQL 执行方法）。详见 04-实体与数据访问。

5.3 定义 Service¶

package cn.cnbm.bams.demo.service;

import cn.cnbm.bams.demo.pojo.DemoProduct;
import cn.cnbm.bams.demo.mapper.DemoProductMapper;
import cn.cnbm.bams.service.ext.IServiceExt;            // 继承这个接口
import cn.cnbm.bams.service.ext.impl.ServiceExtImpl;    // 实现这个基类
import org.springframework.stereotype.Service;

public interface DemoProductService extends IServiceExt<DemoProduct> {
}

@Service
public class DemoProductServiceImpl
        extends ServiceExtImpl<DemoProductMapper, DemoProduct>
        implements DemoProductService {
}

ServiceExtImpl 在 MyBatis-Plus ServiceImpl 基础上增强了：saveOrUpdateExt（带序列号/重复校验/JSR303）、listPage（按参数分页）、tree（树形组装）等。详见 05-业务服务层。

5.4 定义 Controller（核心：继承 EnergyBaseController）¶

package cn.cnbm.bams.demo.controller;

import cn.cnbm.bams.common.func.controller.EnergyBaseController;
import cn.cnbm.bams.demo.pojo.DemoProduct;
import cn.cnbm.bams.demo.service.DemoProductService;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/demo/product")
public class DemoProductController
        extends EnergyBaseController<DemoProductService, DemoProduct> {
    // 空的！全套接口已由父类提供
}

5.5 自动获得的接口¶

启动后，以下接口全部可用（无需写一行代码）：

接口	方法	功能
`/demo/product/list`	POST	分页查询（传 BasicParamWrapper 参数）
`/demo/product/dict`	POST	字典查询（指定列）
`/demo/product/tree`	POST	树形查询（实体需实现 ITreeAble）
`/demo/product/getOne/{id}`	GET	按 id 查询
`/demo/product/saveOrUpdate`	POST	新增/修改（带序列号、校验）
`/demo/product/batchSaveOrUpdate`	POST	批量新增/修改
`/demo/product/delete/{id}`	POST	按 id 删除
`/demo/product/batchDelete`	POST	批量删除
`/demo/product/exportToExcel`	POST	导出 Excel
`/demo/product/importExcelData`	POST	导入 Excel
`/demo/product/generateTemplate`	GET	下载导入模板

EnergyBaseController 的完整接口清单详见 09-通用功能。

6. 构建¶

# 从 bams-sdk 根目录构建安装到本地仓库
cd bams-sdk
mvn clean install -DskipTests

# 然后构建你的业务应用
cd your-app
mvn clean package -DskipTests

注意：bams-sdk 无 Maven Wrapper，需本机已安装 mvn 并加入 PATH。部分开发环境的 .java 源码受 E-SafeNet DRM 加密，但 clone 下来的代码是明文。

7. 下一步¶

了解整体架构 → 02-模块依赖与架构
查工具类用法 → 03-通用工具库
深入数据访问 → 04-实体与数据访问
了解 Service 层增强 → 05-业务服务层