零代码到生产级模块：SmartAdmin 7步极速开发指南

你是否还在为中后台模块开发的重复劳动而困扰？从数据库设计到接口开发，再到前端页面实现，每一步都充满琐碎细节。本文将带你用SmartAdmin平台，7步完成一个生产级「数据字典管理模块」的开发，全程仅需1小时，避开90%的常规踩坑点。

读完本文你将掌握

• 基于SmartAdmin的模块开发全流程最佳实践
• 前后端代码自动生成与手动扩展的平衡技巧
• 三级等保要求下的权限控制与数据安全实现
• 双版本框架（Java/TypeScript）的无缝协同开发

模块开发全景流程图

flowchart TD
    A[需求分析] --> B[数据库设计]
    B --> C[后端接口开发]
    C --> D[权限配置]
    D --> E[前端页面生成]
    E --> F[功能扩展]
    F --> G[测试与部署]
    G --> H[上线]
    style A fill:#f9f,stroke:#333
    style H fill:#9f9,stroke:#333

一、环境准备与项目结构解析

1.1 开发环境配置

# 克隆项目仓库
git clone https://gitcode.com/lab1024/smart-admin
cd smart-admin

# 启动后端服务（Java8+SpringBoot2版本）
cd smart-admin-api-java8-springboot2
mvn clean package -Dmaven.test.skip=true
java -jar sa-admin/target/sa-admin.jar

# 启动前端服务（TypeScript版本）
cd ../smart-admin-web-typescript
npm install
npm run dev

1.2 项目核心结构

SmartAdmin采用前后端分离架构，核心目录结构如下：

smart-admin/
├── smart-admin-api-java8-springboot2/  # Java后端（SpringBoot2版本）
│   └── sa-admin/src/main/java/com/lab1024/smart/admin/
│       ├── controller/                 # 控制器层
│       ├── service/                    # 服务层
│       ├── repository/                 # 数据访问层
│       └── domain/                     # 实体类定义
└── smart-admin-web-typescript/         # Vue前端（TypeScript版本）
    └── src/
        ├── views/                      # 页面组件
        ├── api/                        # API请求定义
        ├── components/                 # 通用组件
        └── router/                     # 路由配置

二、数据库设计（10分钟）

2.1 表结构设计

以「数据字典」模块为例，创建字典类型表(sys_dict_type)和字典项表(sys_dict_item)：

-- 字典类型表
CREATE TABLE sys_dict_type (
  dict_type_id BIGINT PRIMARY KEY AUTO_INCREMENT,
  dict_type_code VARCHAR(50) NOT NULL COMMENT '字典类型编码',
  dict_type_name VARCHAR(100) NOT NULL COMMENT '字典类型名称',
  disabled_flag TINYINT DEFAULT 0 COMMENT '禁用标志(0-启用,1-禁用)',
  remark VARCHAR(500) COMMENT '备注',
  create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
  update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  UNIQUE KEY uk_dict_type_code (dict_type_code)
) COMMENT = '数据字典类型表';

-- 字典项表
CREATE TABLE sys_dict_item (
  dict_item_id BIGINT PRIMARY KEY AUTO_INCREMENT,
  dict_type_id BIGINT NOT NULL COMMENT '字典类型ID',
  dict_label VARCHAR(100) NOT NULL COMMENT '字典标签',
  dict_value VARCHAR(50) NOT NULL COMMENT '字典值',
  sort INT DEFAULT 0 COMMENT '排序',
  disabled_flag TINYINT DEFAULT 0 COMMENT '禁用标志(0-启用,1-禁用)',
  create_time DATETIME DEFAULT CURRENT_TIMESTAMP,
  update_time DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  KEY idx_dict_type_id (dict_type_id)
) COMMENT = '数据字典项表';

2.2 使用代码生成器

SmartAdmin提供内置代码生成器，通过以下步骤生成基础代码：

1. 登录系统，进入「系统工具」→「代码生成」
2. 选择刚创建的两张表，点击「生成代码」
3. 下载生成的压缩包，包含完整的前后端代码

三、后端接口开发（15分钟）

3.1 实体类定义

在domain目录下创建实体类：

@Data
@TableName("sys_dict_type")
public class SysDictType extends BaseEntity {
    private Long dictTypeId;
    private String dictTypeCode;
    private String dictTypeName;
    private Integer disabledFlag;
    private String remark;
}

3.2 控制器实现

创建DictTypeController：

@RestController
@RequestMapping("/api/v1/dict-type")
public class DictTypeController extends BaseController {

    @Autowired
    private DictTypeService dictTypeService;

    @GetMapping("/page")
    @Privilege(value = "system:dict:page")
    public ResponseModel<PageResult<SysDictTypeVO>> page(SysDictTypeQuery query) {
        PageResult<SysDictTypeVO> pageResult = dictTypeService.page(query);
        return ResponseModel.ok(pageResult);
    }

    @PostMapping
    @Privilege(value = "system:dict:add")
    public ResponseModel<String> add(@Valid @RequestBody SysDictTypeAddForm form) {
        dictTypeService.add(form);
        return ResponseModel.ok();
    }

    // 省略更新、删除、详情等接口...
}

四、前端页面开发（20分钟）

4.1 API接口定义

在src/api/support/dict-type-api.ts中定义接口：

import { defHttp } from '/@/lib/axios';

export const dictTypeApi = {
  // 分页查询
  page: (params) => defHttp.get<PageResult<SysDictTypeVO>>({ url: '/api/v1/dict-type/page', params }),
  // 新增
  add: (data) => defHttp.post({ url: '/api/v1/dict-type', data }),
  // 更新
  update: (data) => defHttp.put({ url: '/api/v1/dict-type', data }),
  // 删除
  delete: (id) => defHttp.delete({ url: `/api/v1/dict-type/${id}` }),
  // 详情
  detail: (id) => defHttp.get({ url: `/api/v1/dict-type/${id}` }),
};

4.2 列表页面实现

创建src/views/support/dict-type/dict-type-list.vue：

<template>
  <div>
    <a-form class="smart-query-form">
      <a-row class="smart-query-form-row">
        <a-form-item label="字典编码" class="smart-query-form-item">
          <a-input v-model:value="queryForm.dictTypeCode" placeholder="请输入字典编码" />
        </a-form-item>
        <a-form-item label="字典名称" class="smart-query-form-item">
          <a-input v-model:value="queryForm.dictTypeName" placeholder="请输入字典名称" />
        </a-form-item>
        <a-form-item label="状态" class="smart-query-form-item">
          <SmartEnumSelect v-model:value="queryForm.disabledFlag" enum-name="FLAG_NUMBER_ENUM" />
        </a-form-item>
        <a-form-item>
          <a-button type="primary" @click="query">查询</a-button>
          <a-button @click="resetQuery" style="margin-left: 8px">重置</a-button>
        </a-form-item>
      </a-row>
    </a-form>

    <a-card>
      <div slot="extra">
        <a-button type="primary" @click="showAddModal" v-privilege="'system:dict:add'">
          <PlusOutlined /> 添加
        </a-button>
      </div>
      
      <a-table 
        :columns="columns" 
        :dataSource="tableData" 
        :loading="tableLoading"
        rowKey="dictTypeId"
        :pagination="pagination"
        @change="handleTableChange"
      >
        <template #bodyCell="{ column, record }">
          <template v-if="column.dataIndex === 'disabledFlag'">
            <span>{{ $smartEnumPlugin.getDescByValue('FLAG_NUMBER_ENUM', record.disabledFlag) }}</span>
          </template>
          <template v-if="column.dataIndex === 'operate'">
            <a-button type="link" @click="showEditModal(record)" v-privilege="'system:dict:update'">编辑</a-button>
            <a-button type="link" danger @click="deleteRecord(record)" v-privilege="'system:dict:delete'">删除</a-button>
          </template>
        </template>
      </a-table>
    </a-card>

    <DictTypeModal ref="modal" @reload="query" />
  </div>
</template>

五、权限配置与安全实现（5分钟）

5.1 权限配置

在数据库中添加菜单和权限配置：

-- 插入菜单
INSERT INTO sys_menu (menu_id, parent_id, menu_name, url, component, menu_type, perms, sort, icon) 
VALUES (1001, 0, '数据字典', '/support/dict-type', 'support/dict-type/dict-type-list', 1, 'system:dict', 10, 'icon-dictionary');

-- 插入权限点
INSERT INTO sys_menu (menu_id, parent_id, menu_name, url, component, menu_type, perms, sort) 
VALUES (1002, 1001, '查看', '', '', 2, 'system:dict:page', 1);
INSERT INTO sys_menu (menu_id, parent_id, menu_name, url, component, menu_type, perms, sort) 
VALUES (1003, 1001, '新增', '', '', 2, 'system:dict:add', 2);
INSERT INTO sys_menu (menu_id, parent_id, menu_name, url, component, menu_type, perms, sort) 
VALUES (1004, 1001, '编辑', '', '', 2, 'system:dict:update', 3);
INSERT INTO sys_menu (menu_id, parent_id, menu_name, url, component, menu_type, perms, sort) 
VALUES (1005, 1001, '删除', '', '', 2, 'system:dict:delete', 4);

5.2 权限控制实现

在前端页面中使用权限指令：

<!-- 按钮级别权限控制 -->
<a-button v-privilege="'system:dict:add'">添加</a-button>

<!-- 数据行级别权限控制 -->
<script setup>
import { usePermission } from '/@/hooks/system/usePermission';
const { hasPermission } = usePermission();

// 在方法中判断权限
const canEdit = hasPermission('system:dict:update');
</script>

六、功能测试与优化（10分钟）

6.1 测试用例设计

测试场景	测试步骤	预期结果
列表查询	1. 输入关键字 2. 点击查询按钮	显示符合条件的数据
新增字典	1. 点击添加按钮 2. 填写表单 3. 提交	数据成功入库并刷新列表
编辑功能	1. 点击编辑按钮 2. 修改数据 3. 提交	数据成功更新
删除功能	1. 点击删除按钮 2. 确认删除	数据成功删除
权限控制	使用无权限账号登录	不可见无权限按钮

6.2 性能优化

1. 列表数据缓存

// 在API请求中添加缓存配置
export const dictTypeApi = {
  page: (params) => defHttp.get<PageResult<SysDictTypeVO>>({ 
    url: '/api/v1/dict-type/page', 
    params,
    options: { cacheTime: 3000 }  // 缓存3秒
  }),
};

2. 大数据量分页优化

// 在Service层实现分页查询优化
@Service
public class DictTypeServiceImpl implements DictTypeService {
    @Override
    public PageResult<SysDictTypeVO> page(SysDictTypeQuery query) {
        // 使用MyBatis-Plus分页插件
        Page<SysDictType> page = new Page<>(query.getPageNum(), query.getPageSize());
        QueryWrapper<SysDictType> wrapper = new QueryWrapper<>();
        // 动态SQL条件构建
        if (StringUtils.hasText(query.getDictTypeCode())) {
            wrapper.like("dict_type_code", query.getDictTypeCode());
        }
        // ...其他条件
        
        // 执行分页查询
        Page<SysDictType> resultPage = dictTypeRepository.page(page, wrapper);
        
        // 转换为VO并返回
        return PageResult.of(resultPage, this::convert);
    }
}

七、部署与上线（5分钟）

7.1 后端部署

# 构建生产环境包
cd smart-admin-api-java8-springboot2
mvn clean package -Pprod -Dmaven.test.skip=true

# 部署到服务器
scp sa-admin/target/sa-admin.jar user@server:/opt/smart-admin/
ssh user@server "cd /opt/smart-admin && nohup java -jar sa-admin.jar > app.log 2>&1 &"

7.2 前端部署

# 构建生产环境包
cd smart-admin-web-typescript
npm run build

# 部署到Nginx
scp -r dist/* user@server:/usr/share/nginx/html/smart-admin/

八、扩展功能与最佳实践

8.1 字典缓存与自动加载

在后端实现字典缓存：

@Service
public class DictCacheService {
    private final LoadingCache<String, List<SysDictItemVO>> dictCache;
    
    public DictCacheService() {
        // 创建定时刷新缓存
        this.dictCache = CacheBuilder.newBuilder()
            .expireAfterWrite(1, TimeUnit.HOURS)
            .build(new CacheLoader<String, List<SysDictItemVO>>() {
                @Override
                public List<SysDictItemVO> load(String dictTypeCode) {
                    return dictItemService.queryByDictTypeCode(dictTypeCode);
                }
            });
    }
    
    // 获取字典项
    public List<SysDictItemVO> getDictItems(String dictTypeCode) {
        try {
            return dictCache.get(dictTypeCode);
        } catch (Exception e) {
            log.error("获取字典缓存失败", e);
            return Collections.emptyList();
        }
    }
}

8.2 前端字典组件使用

<template>
  <SmartEnumSelect 
    v-model:value="form.status" 
    enum-name="ORDER_STATUS_ENUM" 
    placeholder="请选择订单状态" 
  />
</template>

总结与展望

通过本文介绍的7步开发法，我们快速构建了一个符合三级等保要求的数据字典管理模块。SmartAdmin平台通过代码生成器、权限框架、安全组件等基础设施，将传统需要2-3天的开发工作压缩到1小时内完成。

后续可以进一步扩展：

1. 添加字典导入导出功能
2. 实现字典变更历史记录
3. 开发字典使用情况分析报表

掌握这种模块化开发方法，你可以轻松应对各类中后台业务需求，让开发效率提升10倍以上。立即动手实践，体验SmartAdmin带来的开发革命！

互动与交流

如果本文对你有帮助，欢迎点赞收藏。有任何疑问或建议，请在评论区留言，作者会在24小时内回复。下一篇我们将深入探讨SmartAdmin的高级特性——动态表单与工作流引擎的实战应用。