当前位置：首页 > news >正文

博客标题：智契通项目开发周记（第一周）：架构设计与基础环境搭建

news 2026/7/9 10:14:15

一、本周工作概述

本周是项目实训的第一周，核心目标并非实现具体的业务功能，而是进行顶层设计与地基建设。基于《智契通》项目需求，我们确立了“Spring Boot 3 + Vue 3 + AI”的技术路线。

主要工作分为两个维度：

架构设计：完成了从需求分析到系统分层、技术选型的总体设计，明确了微服务演进方向。
环境搭建：完成了前后端工程的初始化，重点实现了后端通用异常处理体系、响应封装及前端请求拦截器，为后续AI能力接入打下基础。

二、项目总体架构设计

在编码开始前，我们首先制定了详细的《智契通项目总体架构设计》。一个清晰的架构是应对复杂业务（如合同生成、风险审查）的前提。

1. 技术选型策略
我们采用前后端分离架构，兼顾开发效率与系统扩展性：

后端（Java Spring Boot 3.x）：利用其强大的生态和稳定性，集成Spring Security进行权限控制，使用Redis做缓存，MySQL存储核心数据。
前端（Vue 3 + TypeScript）：采用Vite构建工具，Pinia状态管理，Element Plus组件库，确保现代化的交互体验。
AI能力层：预留OpenAI、通义千问等大模型接口，通过适配器模式支持多模型切换。

2. 系统分层设计
为了保证代码的可维护性，我们严格遵循分层架构：

表现层：Vue前端，负责合同展示、编辑与可视化对比。
接入层：统一API网关（初期由Spring Boot统一处理），负责JWT鉴权与限流。
业务层：核心业务逻辑，包括合同模板、生成、审查、摘要、对比等模块。
AI服务层：独立的模型调用与Prompt编排服务，隔离大模型的不稳定性。
数据层：MySQL + Redis + 对象存储（MinIO），支持海量合同存储。

3. 模块化规划
考虑到项目初期采用单体架构，我们预先规划了模块目录，以便未来拆分为微服务：

contract-user(用户权限)
contract-core(合同核心数据)
contract-ai(AI模型调用)
contract-risk(风险识别)

三、后端基础环境搭建与核心配置

环境搭建不仅仅是引入依赖，更重要的是建立一套规范的代码契约。本周后端工作重点在于“通用能力”的封装。

1. 项目结构规范
基于Maven构建，我们规范了标准的包结构，确保团队成员代码风格统一：

src/ ├── main/ │ ├── java/ │ │ └── com.zhiqitong/ │ │ ├── config/ # 配置类 (如WebConfig, RedisConfig) │ │ ├── controller/ # 接口层 │ │ ├── exception/ # 异常处理体系 │ │ ├── service/ # 业务逻辑层 │ │ ├── util/ # 通用工具类 (Hutool扩展) │ │ └── Application.java │ └── resources/ └── test/

2. 核心依赖整合

Hutool工具库：引入Hutool以简化Java开发。例如，使用IdUtil.getSnowflake()生成分布式唯一ID，避免数据库主键冲突，这在处理大量合同文档时至关重要。
Knife4j接口文档：集成Swagger增强版，实现无注解零配置的接口文档生成，极大方便了前后端联调。

3. 通用异常与响应封装（核心亮点）
为了提升系统的健壮性和前端交互的友好度，我设计了一套完善的异常处理机制。

自定义错误码枚举：
我们定义了标准的错误码体系，与HTTP状态码语义保持一致，便于前端统一处理。

@Getter public enum ErrorCode { SUCCESS(0, "成功"), PARAMS_ERROR(40000, "请求参数错误"), NOT_LOGIN_ERROR(40100, "未登录"), NO_AUTH_ERROR(40101, "无权限"), SYSTEM_ERROR(50000, "系统内部异常"); private final int code; private final String message; // 构造方法... }

全局异常处理器 (GlobalExceptionHandler)：
利用@RestControllerAdvice捕获所有未处理的异常。无论是业务逻辑抛出的BusinessException，还是系统底层的RuntimeException，都会被统一拦截，记录日志并返回标准格式，避免系统崩溃。

@RestControllerAdvice @Slf4j public class GlobalExceptionHandler { @ExceptionHandler(BusinessException.class) public BaseResponse<?> handleBusinessException(BusinessException e) { log.error("BusinessException: ", e); return ResultUtils.error(e.getCode(), e.getMessage()); } @ExceptionHandler(Exception.class) public BaseResponse<?> handleException(Exception e) { log.error("System Error: ", e); return ResultUtils.error(ErrorCode.SYSTEM_ERROR); } }

统一响应包装类 (BaseResponse)：
规范所有接口的返回结构（code, data, message），前端只需一套逻辑即可解析所有接口数据。

四、前端工程化配置与全局设计

前端的任务是打通与后端的通信桥梁，并提供一致的用户体验。

1. Vue 3 工程化架构
采用Vite作为构建工具，TypeScript作为开发语言，Pinia替代 Vuex 进行状态管理。目录结构清晰分离了views（页面）、components（组件）、api（接口请求）和router（路由）。

2. 全局通用布局 (Layout)
参考Ant Design Pro的设计理念，我们设计了BasicLayout。页面采用经典的“上-中-下”结构：

Header：包含Logo、导航菜单及用户头像下拉菜单（集成登录状态检测）。
Content：通过<router-view>动态加载子路由，适配不同屏幕尺寸。
Footer：固定底部的版权信息。

3. 请求层封装与拦截器
为了应对复杂的API调用（特别是后续调用AI接口时的鉴权），我们封装了 Axios 实例：

请求拦截器：统一注入 Token（JWT），处理 Loading 状态。
响应拦截器：核心在于错误统一处理。在拦截器中直接判断后端返回的code：
- 若为40100（未登录），则自动跳转至登录页，无需每个页面单独判断。
- 若为业务错误（如参数错误），则通过Message组件统一弹出提示，极大减少了业务代码中的冗余判断逻辑。

五、遇到的问题与解决方案

Spring Boot 3 的 Jakarta 包冲突
- 问题：Spring Boot 3 默认使用jakarta.servlet，而部分旧版依赖（如Swagger早期版本）使用javax.servlet，导致启动报错。
- 解决：升级Swagger为Knife4j的Spring Boot 3适配版本，并检查依赖树，排除冲突的旧包。
跨域 (CORS) 与 Credentials 配置
- 问题：前端开发服务器（localhost:5173）访问后端（localhost:8080）时，Cookie无法携带，导致登录态丢失。
- 解决：在后端配置@CrossOrigin或自定义CorsConfiguration，并设置allowCredentials为true，同时前端 Axios 配置withCredentials: true。