后端代码结构

SurveyKing Pro 后端采用 Spring Boot 2.7.7 + MyBatis Plus 3.5.2 + Redis + Redisson 技术栈，基于模块化单体架构设计，提供企业级应用框架。

🛠️ 技术栈概览

基于实际项目配置的核心技术栈：

• 应用框架: Spring Boot 2.7.7
• 数据库: MySQL 5.7/8.0+、支持 Oracle、PostgreSQL、达梦 DM 等
• 数据访问: MyBatis Plus 3.5.2 + Druid 1.2.13
• 缓存方案: Redis 5.0 + Redisson 3.17.7
• 安全框架: Spring Security 5.6.5 + OAuth2 Token
• 定时任务: Quartz 2.3.2
• 接口文档: Knife4j 3.0.3 (Swagger 增强)
• 服务保障: Resilience4j 1.7.1 (限流、熔断)
• 监控系统: Spring Boot Admin 2.6.9 + SkyWalking 8.5.0
• 工具库: Hutool 5.8.8、MapStruct 1.5.5、Lombok 1.18.24

📁 项目目录结构

基于实际的项目模块结构：

server/
├── surveyking-dependencies/           # Maven 依赖版本管理
│   └── pom.xml                        # BOM 统一依赖版本 (577行)
├── surveyking-framework/              # 框架技术组件 (25个模块)
│   ├── surveyking-common/             # 通用组件
│   ├── surveyking-spring-boot-starter-web/        # Web 框架封装
│   ├── surveyking-spring-boot-starter-security/   # 安全认证框架
│   ├── surveyking-spring-boot-starter-mybatis/    # 数据库操作框架
│   ├── surveyking-spring-boot-starter-redis/      # Redis 缓存框架
│   ├── surveyking-spring-boot-starter-mq/         # 消息队列框架
│   ├── surveyking-spring-boot-starter-job/        # 定时任务框架
│   ├── surveyking-spring-boot-starter-file/       # 文件操作框架
│   ├── surveyking-spring-boot-starter-excel/      # Excel 处理框架
│   ├── surveyking-spring-boot-starter-captcha/    # 验证码框架
│   ├── surveyking-spring-boot-starter-monitor/    # 监控框架
│   ├── surveyking-spring-boot-starter-test/       # 测试框架
│   ├── surveyking-spring-boot-starter-banner/     # 启动横幅
│   ├── surveyking-spring-boot-starter-word/       # Word 文档处理
│   ├── surveyking-spring-boot-starter-spss/       # SPSS 数据处理
│   ├── surveyking-spring-boot-starter-elasticsearch/ # 搜索引擎
│   ├── surveyking-spring-boot-starter-ocr/        # OCR 识别
│   ├── surveyking-spring-boot-starter-translation/ # 翻译服务
│   └── surveyking-spring-boot-starter-biz-*/      # 业务组件库
│       ├── biz-operatelog/            # 操作日志
│       ├── biz-dict/                  # 字典管理
│       ├── biz-sms/                   # 短信服务
│       ├── biz-weixin/                # 微信集成
│       ├── biz-social/                # 社交登录
│       ├── biz-data-permission/       # 数据权限
│       └── biz-error-code/            # 错误码管理
├── surveyking-module-system/          # 系统功能模块
│   ├── surveyking-module-system-api/  # 系统模块API定义
│   └── surveyking-module-system-biz/  # 系统模块具体实现
├── surveyking-module-survey/          # 问卷功能模块
│   ├── surveyking-module-survey-api/  # 问卷模块API定义
│   └── surveyking-module-survey-biz/  # 问卷模块具体实现
├── surveyking-module-infra/           # 基础设施模块
│   ├── surveyking-module-infra-api/   # 基础设施API定义
│   └── surveyking-module-infra-biz/   # 基础设施具体实现
├── surveyking-module-report/          # 报表功能模块
│   ├── surveyking-module-report-api/  # 报表模块API定义
│   └── surveyking-module-report-biz/  # 报表模块具体实现
├── surveyking-module-wechat-enterprise/ # 企业微信模块
├── surveyking-module-ai/              # AI 功能模块
├── surveyking-module-poster/          # 海报生成模块
├── surveyking-module-dbsync/          # 数据同步模块
├── surveyking-server/                 # 主应用服务器
│   ├── src/main/java/                 # Java 源码
│   ├── src/main/resources/            # 配置资源
│   │   ├── application.yml            # 应用配置
│   │   ├── application-dev.yml        # 开发环境配置
│   │   └── application-prod.yml       # 生产环境配置
│   ├── Dockerfile                     # Docker 构建文件
│   └── pom.xml                        # 服务器依赖配置
├── surveyking-example/                # 示例项目
│   ├── surveyking-sso-demo-by-code/   # SSO 授权码示例
│   └── surveyking-sso-demo-by-password/ # SSO 密码示例
├── sql/                               # 数据库脚本
├── bin/                               # 部署脚本
├── Jenkinsfile                        # Jenkins 持续集成
└── pom.xml                           # 父 POM 配置

🏗️ 模块化架构设计

📦 模块分层架构

1. Dependencies 层

• surveyking-dependencies: Maven BOM，统一管理所有依赖版本
• 避免依赖冲突，确保版本一致性
• 包含 Spring Boot、数据库、缓存、工具类等 40+ 个主要依赖

2. Framework 层 (25 个技术组件)

核心技术组件：

• web: Web 框架封装，全局异常处理、访问日志、跨域配置
• security: 认证授权框架，基于 Spring Security + JWT
• mybatis: 数据库操作框架，基于 MyBatis Plus + 多数据源
• redis: 缓存框架，基于 Redis + Redisson 分布式锁
• mq: 消息队列框架，基于 Redis Stream 实现
• job: 定时任务框架，基于 Quartz 集群调度

功能技术组件：

• file: 文件服务，支持本地、MinIO、阿里云 OSS 等
• excel: Excel 处理，基于 EasyExcel 导入导出
• captcha: 验证码服务，支持图形、滑块验证
• monitor: 系统监控，集成 Spring Boot Admin
• word: Word 文档处理，支持模板生成
• spss: SPSS 数据分析集成
• elasticsearch: 搜索引擎集成
• ocr: OCR 文字识别服务
• translation: 翻译服务集成

业务技术组件：

• biz-operatelog: 操作日志记录
• biz-dict: 字典数据管理
• biz-sms: 短信服务，支持阿里云、腾讯云
• biz-weixin: 微信生态集成
• biz-social: 社交登录，支持第三方登录
• biz-data-permission: 数据权限控制
• biz-error-code: 统一错误码管理

3. Module 层 (业务模块)

每个业务模块采用 API + BIZ 分层设计：

// API 模块职责
- 定义接口契约 (Controller Interface)
- 定义数据传输对象 (DTO/VO)
- 定义业务异常
- 定义常量枚举

// BIZ 模块职责
- 具体业务实现 (Controller/Service/Mapper)
- 数据库实体定义 (Entity)
- 业务逻辑处理
- 数据访问层实现

核心业务模块：

• system: 系统管理（用户、角色、权限、字典等）
• survey: 问卷管理（问卷设计、数据收集、统计分析）
• infra: 基础设施（配置、文件、日志、监控等）
• report: 报表中心（数据报表、图形报表）

扩展业务模块：

• wechat-enterprise: 企业微信集成
• ai: AI 功能（智能分析、自动生成等）
• poster: 海报生成服务
• dbsync: 数据同步服务

4. Server 层

• surveyking-server: 主应用启动器，整合所有模块
• 提供统一的应用入口和配置管理

🔄 模块依赖关系

🏗️ 分层架构设计

控制器层 (Controller)

@RestController
@RequestMapping("/survey")
@Slf4j
public class ProjectController {

    @Autowired
    private ProjectService projectService;

    @GetMapping("/page")
    @Operation(summary = "获取项目列表")
    public CommonResult<PageResult<ProjectRespVO>> getProjects(
            @Valid ProjectPageReqVO pageReqVO) {
        PageResult<Project> pageResult = projectService.getProjectPage(pageReqVO);
        return success(ProjectConvert.INSTANCE.convertPage(pageResult));
    }

    @PostMapping("/create")
    @Operation(summary = "创建项目")
    public CommonResult<String> createProject(@Valid @RequestBody ProjectCreateReqVO createReqVO) {
        return success(projectService.createProject(createReqVO));
    }
}

服务层 (Service)

@Service
@Transactional(rollbackFor = Exception.class)
public class ProjectServiceImpl implements ProjectService {

    @Resource
    private ProjectMapper projectMapper;

    @Override
    public PageResult<Project> getProjectPage(ProjectPageReqVO pageReqVO) {
        return projectMapper.selectPage(pageReqVO);
    }

    @Override
    public String createProject(ProjectCreateReqVO createReqVO) {
        // 数据校验
        validateProjectForCreateOrUpdate(null, createReqVO.getName());

        // 创建项目
        Project project = ProjectConvert.INSTANCE.convert(createReqVO);
        project.setStatus(ProjectStatusEnum.DRAFT.getStatus());
        projectMapper.insert(project);

        return project.getId();
    }
}

数据访问层 (Mapper)

@Mapper
public interface ProjectMapper extends BaseMapperX<Project> {

    default PageResult<Project> selectPage(ProjectPageReqVO reqVO) {
        return selectPage(reqVO, new LambdaQueryWrapperX<Project>()
                .likeIfPresent(Project::getName, reqVO.getName())
                .eqIfPresent(Project::getStatus, reqVO.getStatus())
                .eqIfPresent(Project::getMode, reqVO.getMode())
                .betweenIfPresent(Project::getCreateTime, reqVO.getCreateTime())
                .orderByDesc(Project::getId));
    }

    default List<Project> selectListByUserId(String userId) {
        return selectList(new LambdaQueryWrapperX<Project>()
                .eq(Project::getCreator, userId)
                .eq(Project::getDeleted, false));
    }
}

🎯 核心实体设计

基础实体类

@Data
@TableName(value = "survey_project", autoResultMap = true)
@EqualsAndHashCode(callSuper = false)
@Builder
@NoArgsConstructor
@AllArgsConstructor
public class Project extends BaseDO {

    /**
     * 项目ID
     */
    private String id;

    /**
     * 项目名称
     */
    private String name;

    /**
     * 语言环境
     */
    private String locale;

    /**
     * 父项目ID，0表示不存在父项目
     */
    private String parentId;

    /**
     * 项目模式：survey问卷 exam考试
     */
    private ProjectModeEnum mode;

    /**
     * 问卷结构 JSON
     */
    @TableField(typeHandler = JacksonTypeHandler.class, jdbcType = JdbcType.LONGVARCHAR)
    private SurveySchema survey;

    /**
     * 项目配置 JSON
     */
    @TableField(typeHandler = JacksonTypeHandler.class, jdbcType = JdbcType.LONGNVARCHAR)
    private ProjectSetting setting;

    /**
     * 发布状态：1已发布 0未发布
     */
    private Integer status;

    /**
     * 优先级，值越小优先级越高
     */
    private Long priority;
}

@Data
public abstract class BaseDO {

    /**
     * 创建时间
     */
    @TableField(fill = FieldFill.INSERT)
    private LocalDateTime createTime;

    /**
     * 最后更新时间
     */
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private LocalDateTime updateTime;

    /**
     * 创建者
     */
    @TableField(fill = FieldFill.INSERT)
    private String creator;

    /**
     * 更新者
     */
    @TableField(fill = FieldFill.INSERT_UPDATE)
    private String updater;

    /**
     * 是否删除
     */
    @TableLogic
    private Boolean deleted;
}

🔧 框架特性

1. 统一响应结构

@Data
public class CommonResult<T> {
    /**
     * 错误码
     */
    private Integer code;

    /**
     * 返回数据
     */
    private T data;

    /**
     * 错误提示
     */
    private String msg;

    public static <T> CommonResult<T> success(T data) {
        CommonResult<T> result = new CommonResult<>();
        result.code = GlobalErrorCodeConstants.SUCCESS.getCode();
        result.data = data;
        result.msg = "操作成功";
        return result;
    }
}

2. 分页查询支持

@Data
public class PageResult<T> {
    /**
     * 数据列表
     */
    private List<T> list;

    /**
     * 总数量
     */
    private Long total;

    /**
     * 当前页码
     */
    private Long current;

    /**
     * 每页数量
     */
    private Long size;
}

3. 数据权限控制

@DataPermission(
    enable = true,
    includeRoles = {"admin", "manager"},
    excludeRoles = {"guest"}
)
public PageResult<Project> getProjectPage(ProjectPageReqVO pageReqVO) {
    // 会自动注入数据权限 SQL
    return projectMapper.selectPage(pageReqVO);
}

🚀 开发特性

1. 自动化代码生成

• 基于数据库表结构生成完整的 CRUD 代码
• 包含 Controller、Service、Mapper、VO 等所有层次
• 支持单元测试代码生成
• 自动生成 Swagger 接口文档

2. 多数据源支持

spring:
  datasource:
    dynamic:
      primary: master
      datasource:
        master:
          url: jdbc:mysql://localhost:3306/surveyking
          username: root
          password: password
        slave:
          url: jdbc:mysql://localhost:3306/surveyking_read
          username: readonly
          password: readonly

3. 分布式锁

@RedissonLock(key = "project:create:#{#createReqVO.name}")
public String createProject(ProjectCreateReqVO createReqVO) {
    // 业务逻辑，自动获取分布式锁
    return projectService.create(createReqVO);
}

4. 操作日志

@OperateLog(type = PROJECT_CREATE, content = "创建项目：{{#project.name}}")
public String createProject(@LogRecordParam("project") ProjectCreateReqVO createReqVO) {
    // 自动记录操作日志
    return projectService.create(createReqVO);
}

📊 性能优化

1. 多级缓存

• 本地缓存: 使用 Caffeine 缓存热点数据
• 分布式缓存: 使用 Redis 共享缓存
• 数据库缓存: MyBatis Plus 二级缓存

2. 异步处理

• 基于 Redis Stream 的消息队列
• 异步处理文件上传、邮件发送等耗时操作
• 支持消息重试和死信队列

3. 数据库优化

• 读写分离支持
• 分页查询优化
• SQL 监控和慢查询分析

---

总结: SurveyKing Pro 后端采用了成熟的企业级架构设计，通过模块化拆分和丰富的技术组件，为复杂的问卷调研业务提供了强大的技术支撑和开发效率。

下一步: 查看 系统配置 了解详细的配置说明。