YuCafeNote Backend

咖啡笔记应用后端服务，基于 Spring Boot 3.5 + MyBatis Plus 构建，提供咖啡豆库存管理、冲煮笔记记录等功能。

技术栈

技术	版本
Java	17
Spring Boot	3.5.15
MyBatis Plus	3.5.7
MySQL	8.0
JWT (jjwt)	0.12.6
Docker	多阶段构建

项目结构


src/main/java/org/wutong/yucafenote/
├── config/                 # 配置类
│   ├── WebConfig.java      # 拦截器注册
│   ├── MybatisPlusConfig   # 分页插件
│   ├── JacksonConfig       # JSON 序列化配置
│   ├── MyMetaObjectHandler # 自动填充时间字段
│   └── interceptor/
│       └── AuthInterceptor # JWT 鉴权拦截器
├── controller/             # 控制器层
│   ├── AuthController      # 登录/刷新令牌
│   ├── UserController      # 普通用户接口
│   ├── AdminUserController # 管理员用户接口
│   ├── CoffeeBeanController# 咖啡豆 CRUD
│   └── CoffeeNoteController# 咖啡笔记 CRUD
├── service/                # 服务接口
│   └── impl/               # 服务实现
├── mapper/                 # MyBatis Mapper
├── model/
│   ├── entity/             # 数据库实体
│   ├── dto/                # 请求参数
│   └── vo/                 # 返回视图
├── common/                 # 通用类 (Result, PageResult)
└── utils/                  # 工具类 (JwtUtil, BeanUtil)

数据库表

表名	说明	主要字段
`user`	用户表	id, username, password, nickname, avatar, email, phone, status, role
`coffee_bean`	咖啡豆表	id, name, brand, varieties, country, roast_date, roast_level, stock, 等 29 个字段
`coffee_note`	咖啡笔记表	id, bean_id, weight, brewing_devices, brew_ratio, 等 13 个字段
`refresh_token`	刷新令牌表	id, user_id, token, expire_time

建表脚本见 db/init.sql。

API 接口

基础路径：/api

认证

方法	路径	说明
POST	`/auth/login`	登录，返回 accessToken + refreshToken + 用户信息
POST	`/auth/refresh`	刷新令牌（Header: `X-Refresh-Token`）

用户

方法	路径	说明
POST	`/users/register`	注册
GET	`/users/me`	获取个人信息
PUT	`/users/me`	修改个人信息

管理员

方法	路径	说明
GET	`/admin/users`	分页查询用户
GET	`/admin/users/{id}`	获取单个用户
POST	`/admin/users`	创建用户
PUT	`/admin/users/{id}`	修改用户
DELETE	`/admin/users/{id}`	删除用户

咖啡豆

方法	路径	说明
GET	`/coffee-beans`	分页查询（按 stock/编辑时间/创建时间降序）
GET	`/coffee-beans/search`	模糊搜索（name/brand/varieties/country）
GET	`/coffee-beans/{id}`	获取详情
POST	`/coffee-beans`	创建
PUT	`/coffee-beans/{id}`	更新
PATCH	`/coffee-beans/{id}/stock`	更新库存
PATCH	`/coffee-beans/{id}/stock/reduce`	减少库存
POST	`/coffee-beans/batch-delete`	批量删除
DELETE	`/coffee-beans/{id}`	删除

咖啡笔记

方法	路径	说明
GET	`/coffee-notes`	分页查询（含关联咖啡豆信息）
GET	`/coffee-notes/search`	按咖啡豆字段模糊搜索
GET	`/coffee-notes/{id}`	获取详情
POST	`/coffee-notes`	创建
PUT	`/coffee-notes/{id}`	更新
POST	`/coffee-notes/batch-delete`	批量删除
DELETE	`/coffee-notes/{id}`	删除

完整接口文档见 docs/api/openapi.yaml。

鉴权机制

双 Token 模式：JWT accessToken（24h 有效期）+ UUID refreshToken（30 天有效期，到期前 15 天内续期）
请求头携带 Authorization: <accessToken>（兼容 Bearer <token> 格式）
公开接口：/auth/**、/users/register，其余均需鉴权

业务规则

普通用户只能操作自己创建的咖啡豆和笔记
管理员拥有用户管理权限，咖啡豆和笔记仍按创建者隔离
咖啡豆排序：库存 DESC → 编辑时间 DESC → 创建时间 DESC → 烘焙日期 ASC
笔记排序：关联咖啡豆库存 DESC → 笔记编辑时间 DESC → 笔记创建时间 DESC
删除为逻辑删除（放入回收站），is_delete 字段标记
减少库存时校验存量，不足则拒绝
API 返回的 String 字段 null 统一转空字符串 ""

本地开发


# 1. 启动 MySQL 并执行初始化
mysql -u root -p < db/init.sql
 
# 2. 修改 application.yml 中的数据库连接信息
 
# 3. 启动项目
mvn spring-boot:run

服务运行在 http://localhost:8101/api。

部署

详见 docs/deploy.md，简要流程：

服务器安装 Docker 和 Docker Compose
配置 GitHub Secrets：SERVER_HOST、SERVER_USER、SSH_PRIVATE_KEY、DB_PASSWORD
服务器初始化目录并创建 .env
上传 db/init.sql 和 docker-compose.yml
推送代码到 main 分支，GitHub Actions 自动构建镜像并部署

Docker 架构


docker-compose.yml
├── mysql (8.0, 256MB 内存限制, 健康检查)
└── app   (JRE 17, 384MB 内存限制, JVM -Xmx256m)

CI/CD 流程


Git Push → GitHub Actions
  ├── Maven 编译
  ├── Docker 镜像构建
  ├── 推送至 ghcr.io
  └── SSH 到服务器 → docker-compose pull & up

运维


# 查看应用日志
sudo docker logs yucafenote-app
 
# 重启应用
cd /opt/yucafenote && sudo docker-compose restart app
 
# 查看容器状态
cd /opt/yucafenote && sudo docker-compose ps
 
# 进入数据库
sudo docker exec -it yucafenote-db mysql -u root -p
 
# 查看资源占用
docker stats --no-stream

1G 内存服务器优化

MySQL 限制 256MB，关闭 performance_schema，innodb_buffer_pool_size=64M
应用限制 384MB，JVM 使用 SerialGC + 延迟初始化
建议开启 swap（至少 1G）

许可证

MIT