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

PetLumina-02-后端开发与前后端联调

news 2026/6/9 8:50:16

title: PetLumina 02 — Spring Boot 后端开发与前后端联调
date: 2026-05-21
tags:

PetLumina
Spring Boot
MyBatis-Plus
Sa-Token
AI开发
categories:
项目实战
description: 使用 Spring Boot 2.7 + MyBatis-Plus 3.5 + Sa-Token 1.39 搭建后端服务，完成数据库设计、统一认证、接口规范，并与前端联调。

PetLumina 02 — Spring Boot 后端开发与前后端联调

Mock 阶段定义的数据结构，就是后端的 API 契约。按契约开发，联调零障碍。

一、技术选型与架构设计

1.1 技术栈

技术	版本	用途	选型理由
Spring Boot	2.7.x	基础框架	生态成熟，文档丰富
MyBatis-Plus	3.5.x	ORM	比原生 MyBatis 简洁，内置分页/逻辑删除
Sa-Token	1.39.x	权限认证	比 Spring Security 轻量，注解式鉴权
MySQL	8.0	数据库	项目规模不需要分布式数据库
Redis	7.x	缓存	Sa-Token 默认使用 Redis 做 Session 存储

1.2 包结构设计

backend/src/main/java/com/petlumina/backend/ ├── annotation/ # 自定义注解 │ ├── AuthCheck.java # 权限校验注解 │ └── RateLimiter.java# 限流注解 ├── aop/ # 切面 │ ├── AuthCheckAspect.java │ └── RedisRateLimiterAspect.java ├── common/ # 公共类 │ ├── BaseResponse.java # 统一响应 │ ├── ResultUtils.java # 响应工具 │ ├── PageRequest.java # 分页请求基类 │ └── DeleteRequest.java # 删除请求 ├── config/ # 配置类 │ ├── JsonConfig.java # JSON 序列化 │ ├── CorsFilterConfig.java # 跨域配置 │ ├── MybatisPlusConfig.java # MP 配置 │ ├── SaTokenConfigure.java # Sa-Token 配置 │ └── AsyncConfig.java # 异步配置 ├── constant/ # 常量 │ ├── CosConstant.java # COS 路径常量 │ ├── RedisConstant.java # Redis Key 常量 │ └── UserConstant.java # 用户角色常量 ├── controller/ │ ├── admin/ # 管理端接口 │ └── user/ # 用户端接口 ├── model/ │ ├── entity/ # 数据库实体 │ ├── vo/ # 视图对象（返回前端） │ └── dto/ # 数据传输对象（接收参数） ├── mapper/ # MyBatis Mapper ├── service/ # 业务逻辑 │ └── impl/ ├── manager/ # 第三方服务管理 │ └── cos/ # COS 文件管理 ├── exception/ # 异常处理 └── utils/ # 工具类

为什么分admin/和user/两套 Controller？

管理端和用户端的接口路径、权限校验、数据范围完全不同。管理端需要管理员权限，用户端只需要登录。分开后，权限注解、路径前缀、业务逻辑都清晰。

二、数据库设计

2.1 核心表结构

-- 用户表CREATETABLE`user`(`id`BIGINTNOTNULLCOMMENT'雪花ID',`username`VARCHAR(50)NOTNULLCOMMENT'用户名',`password`VARCHAR(128)NOTNULLCOMMENT'密码(BCrypt)',`nickname`VARCHAR(50)DEFAULTNULLCOMMENT'昵称',`avatar`VARCHAR(255)DEFAULTNULLCOMMENT'头像URL',`phone`VARCHAR(20)DEFAULTNULLCOMMENT'手机号',`role`TINYINTDEFAULT0COMMENT'0普通用户 1管理员',`create_time`DATETIMEDEFAULTCURRENT_TIMESTAMP,`update_time`DATETIMEDEFAULTCURRENT_TIMESTAMPONUPDATECURRENT_TIMESTAMP,`is_delete`TINYINTDEFAULT0COMMENT'逻辑删除',PRIMARYKEY(`id`),UNIQUEKEY`uk_username`(`username`))ENGINE=InnoDBDEFAULTCHARSET=utf8mb4;-- 宠物表CREATETABLE`pet`(`id`BIGINTNOTNULL,`user_id`BIGINTNOTNULLCOMMENT'宠物主人ID',`name`VARCHAR(50)NOTNULLCOMMENT'宠物名字',`type`VARCHAR(20)DEFAULTNULLCOMMENT'类型(cat/dog/other)',`breed`VARCHAR(50)DEFAULTNULLCOMMENT'品种',`avatar`VARCHAR(255)DEFAULTNULLCOMMENT'头像URL',`birthday`DATEDEFAULTNULLCOMMENT'生日',`weight`DECIMAL(5,2)DEFAULTNULLCOMMENT'体重(kg)',`gender`TINYINTDEFAULT0COMMENT'0未知 1公 2母',`create_time`DATETIMEDEFAULTCURRENT_TIMESTAMP,`update_time`DATETIMEDEFAULTCURRENT_TIMESTAMPONUPDATECURRENT_TIMESTAMP,`is_delete`TINYINTDEFAULT0,PRIMARYKEY(`id`),KEY`idx_user_id`(`user_id`))ENGINE=InnoDBDEFAULTCHARSET=utf8mb4;

2.2 设计要点

为什么用 BIGINT 而不是 INT 做主键？

雪花算法生成的 ID 是 19 位数字，INT 最大只有 21 亿（10 位），BIGINT 最大 9.2×10^18（19 位），刚好够用。

为什么用is_delete逻辑删除？

用户数据不能物理删除 — 宠物记录、健康数据、帖子等都有关联关系。物理删除会导致外键断裂、数据不一致。逻辑删除只是标记状态，数据还在。

三、统一响应封装

// common/BaseResponse.java@DatapublicclassBaseResponse<T>implementsSerializable{privateintcode;// 状态码privateStringmessage;// 提示信息privateTdata;// 数据publicBaseResponse(intcode,Tdata,Stringmessage){this.code=code;this.data=data;this.message=message;}publicBaseResponse(intcode,Tdata){this(code,data,"");}publicBaseResponse(ErrorCodeerrorCode){this(errorCode.getCode(),null,errorCode.getMessage());}}// common/ResultUtils.javapublicclassResultUtils{publicstatic<T>BaseResponse<T>success(Tdata){returnnewBaseResponse<>(0,data,"ok");}publicstaticBaseResponse<?>error(ErrorCodeerrorCode){returnnewBaseResponse<>(errorCode);}publicstaticBaseResponse<?>error(intcode,Stringmessage){returnnewBaseResponse<>(code,null,message);}}

code=0 表示成功— 和前端约定好，前端只判断code === 0，其他一律为失败。

四、Sa-Token 认证配置

4.1 依赖配置

# application.ymlsa-token:token-name:satokentimeout:86400# Token 有效期 24 小时is-concurrent:true# 允许同一账号并发登录is-share:true# 同端共享 Tokentoken-style:uuid# Token 格式

4.2 拦截器配置

// config/SaTokenConfigure.java@ConfigurationpublicclassSaTokenConfigureimplementsWebMvcConfigurer{@OverridepublicvoidaddInterceptors(InterceptorRegistryregistry){registry.addInterceptor(newSaInterceptor(handle->{// 管理端接口 — 必须管理员角色SaRouter.match("/api/v1/admin/**").check(r->StpUtil.checkRole("admin"));// 用户端接口 — 必须登录（排除登录/注册）SaRouter.match("/api/v1/**").notMatch("/api/v1/user/login","/api/v1/user/register").check(r->StpUtil.checkLogin());})).addPathPatterns("/api/**");}}

Sa-Token 的路由匹配比 Spring Security 简洁很多—SaRouter.match().check()一行搞定一个规则。

五、MyBatis-Plus 配置

5.1 自动填充

// config/MyMetaObjectHandler.java@ComponentpublicclassMyMetaObjectHandlerimplementsMetaObjectHandler{@OverridepublicvoidinsertFill(MetaObjectmetaObject){this.strictInsertFill(metaObject,"createTime",Date.class,newDate());this.strictInsertFill(metaObject,"updateTime",Date.class,newDate());}@OverridepublicvoidupdateFill(MetaObjectmetaObject){this.strictUpdateFill(metaObject,"updateTime",Date.class,newDate());}}

5.2 实体类注解

// model/entity/Pet.java@Data@TableName("pet")publicclassPetimplementsSerializable{@TableId(type=IdType.ASSIGN_ID)// 雪花 IDprivateLongid;privateLonguserId;privateStringname;privateStringtype;privateStringbreed;privateStringavatar;privateDatebirthday;privateDoubleweight;privateIntegergender;@TableField(fill=FieldFill.INSERT)privateDatecreateTime;@TableField(fill=FieldFill.INSERT_UPDATE)privateDateupdateTime;@TableLogic// 逻辑删除privateIntegerisDelete;}

六、前端请求层改造

6.1 Axios 实例

// api/request.tsconstrequest=axios.create({baseURL:import.meta.env.VITE_API_BASE_URL||'/api/v1',timeout:10000,})// 请求拦截器 — 注入 Tokenrequest.interceptors.request.use(config=>{consttoken=localStorage.getItem('satoken')if(token){config.headers['satoken']=token// Sa-Token 的 Header 名}returnconfig})// 响应拦截器 — 统一处理request.interceptors.response.use(response=>{constres=response.dataif(res.code!==0){showToast(res.message||'请求失败')if(res.code===40100){// 未登录localStorage.removeItem('satoken')window.location.hash='#/login'}returnPromise.reject(newError(res.message))}returnres.data// 直接返回 data，不包装在 BaseResponse 中})

6.2 接口模块化

// api/pet.tsexportconstpetApi={getList:()=>request.get('/pet/list'),getDetail:(id:string)=>request.get('/pet/detail',{params:{id}}),add:(data:any)=>request.post('/pet/add',data),update:(data:any)=>request.post('/pet/update',data),delete:(id:string)=>request.post('/pet/delete',{id}),}

七、跨域配置

// config/CorsFilterConfig.java@ConfigurationpublicclassCorsFilterConfig{@BeanpublicCorsFiltercorsFilter(){UrlBasedCorsConfigurationSourcesource=newUrlBasedCorsConfigurationSource();CorsConfigurationconfig=newCorsConfiguration();config.setAllowCredentials(true);config.addAllowedOriginPattern("*");config.addAllowedHeader("*");config.addAllowedMethod("*");source.registerCorsConfiguration("/api/**",config);returnnewCorsFilter(source);}}

为什么用addAllowedOriginPattern("*")而不是addAllowedOrigin("*")？

allowCredentials(true)和addAllowedOrigin("*")不能同时使用 — 这是 CORS 规范的限制。addAllowedOriginPattern("*")是 Spring Boot 2.4+ 提供的替代方案。

八、踩坑记录

8.1 QueryWrapper 字段名

// ❌ 错误 — 驼峰是 Java 属性名，不是数据库字段名queryWrapper.eq("createTime",date);// ✅ 正确 — 数据库字段是下划线queryWrapper.eq("create_time",date);

MyBatis-Plus 的QueryWrapper使用的是数据库字段名，不是 Java 属性名。这个错误在后面的用户管理、宠物管理、帖子管理中反复出现。

8.2 Sa-Token 登录接口

@PostMapping("/login")publicBaseResponse<UserVO>login(@RequestBodyUserLoginRequestrequest){// 查询用户Useruser=userService.lambdaQuery().eq(User::getUsername,request.getUsername()).one();if(user==null||!BCrypt.checkpw(request.getPassword(),user.getPassword())){returnResultUtils.error(ErrorCode.PARAMS_ERROR,"用户名或密码错误");}// Sa-Token 登录 — 会自动生成 Token 并写入 RedisStpUtil.login(user.getId());// 返回用户信息 + TokenUserVOvo=UserVO.objToVo(user);vo.setToken(StpUtil.getTokenValue());returnResultUtils.success(vo);}