cat_shark
64 lines
2.5 KiB
Markdown
64 lines
2.5 KiB
Markdown
# LPT 后端规范
|
||
|
||
## 技术栈
|
||
- Java 17, Spring Boot 3.2.5
|
||
- MyBatis-Plus 3.5.5 + MySQL
|
||
- MapStruct 1.5.5（编译期生成代码，DTO 增删字段后需重新编译）
|
||
- Sa-Token 1.38.0（认证/鉴权）
|
||
- Flyway（数据库迁移）
|
||
- Lombok（@Data, @Slf4j）
|
||
|
||
## 项目结构
|
||
```
|
||
controller/ → REST 接口，只做参数校验和路由
|
||
service/ → 业务逻辑
|
||
impl/
|
||
mapper/ → MyBatis-Plus BaseMapper
|
||
entity/ → 数据库实体（@TableName, @TableField）
|
||
dto/ → 请求/响应 DTO
|
||
request/
|
||
response/
|
||
config/ → Spring 配置（WebMvcConfig, JacksonConfig 等）
|
||
utils/ → 工具类
|
||
common/ → GlobalExceptionHandler, Ops 等
|
||
mapStruct/ → MapStruct Converter 接口
|
||
```
|
||
|
||
## 响应规范
|
||
- 统一使用 `CommonResult<T>` 包装：`{ code, message, data }`
|
||
- 成功：`CommonResult.success(data)` → code=200
|
||
- 业务错误：`CommonResult.error(msg)` → code=400, HTTP 200
|
||
- 未登录：`GlobalExceptionHandler.handleNotLogin()` → HTTP 401 + code=401
|
||
- 参数校验失败走 `MethodArgumentNotValidException` → code=400
|
||
|
||
## 认证
|
||
- SaInterceptor 注册在 `WebMvcConfig`（无 @Profile 限制，所有环境生效）
|
||
- 拦截 `/**`，排除 `/login`
|
||
- `StpUtil.checkLogin()` 失败 → NotLoginException → GlobalExceptionHandler → 401
|
||
- Cookie 名 `satoken`，前端 axios 需 `withCredentials: true`
|
||
|
||
## 数据库变更
|
||
- Flyway 迁移文件：`src/main/resources/db/migration/V{日期}_{序号}__{描述}.sql`
|
||
- 文件名日期格式：`yyyyMMdd`
|
||
|
||
## DTO 转换
|
||
- MapStruct 编译期生成 `*ConvertImpl.java`（target/generated-sources/）
|
||
- 同名属性自动映射，`unmappedTargetPolicy = IGNORE`
|
||
- 如需自定义映射用 `@Mapping(source, target)`
|
||
- **增删 DTO 字段后必须重新编译**，否则 MapStruct 生成代码不含新字段
|
||
|
||
## CORS
|
||
- 由 `CorsProperties` 读取各 profile 的 `cors.allowed-origins` 配置
|
||
- `allowed-origins: "*"` 时自动切换为 `allowedOriginPatterns("*")`（兼容 allowCredentials）
|
||
- local profile：`allow-credentials: true`, `allowed-origins: '*'`
|
||
|
||
## 标题抓取
|
||
- `TitleFetcher`：静态工具类，支持手动跟随 HTTP→HTTPS 重定向、宽松 SSL
|
||
- `UtilsController`：`GET /utils/fetch-title?url=...` 代理端点
|
||
|
||
## 运行
|
||
- 默认 profile：local（application.yml 中 `spring.profiles.active: local`）
|
||
- IDEA JDK：`C:/Users/cat-win/.jdks/ms-17.0.19`
|
||
- Maven：IDEA 内置 `C:/Program Files/JetBrains/IntelliJ IDEA 2026.1.3/plugins/maven/lib/maven3/bin/mvn`
|
||
- 编译：`mvn clean compile -DskipTests`（须用 JDK 17）
|