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

一、 本周工作概述本周是项目实训的第一周核心目标并非实现具体的业务功能而是进行顶层设计与地基建设。基于《智契通》项目需求我们确立了“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 实例请求拦截器统一注入 TokenJWT处理 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。