docs(knowledge): 添加测试知识库文档
新增 6 个知识库文档，用于测试 L0+L1 混合检索功能： API 类： - payment-errors.md - 支付网关错误码定义 领域知识类： - spring-ai-tool-best-practices.md - Spring AI 工具定义最佳实践 基础设施类： - redis-config.md - Redis 缓存配置指南 - mysql-connection-pool.md - MySQL 连接池配置 - flyway-best-practices.md - Flyway 数据库迁移最佳实践 故障排查类： - fault-diagnosis-process.md - 故障诊断流程规范 所有文档均包含： - 标准 frontmatter 元数据 (title, keywords, summary, category) - 实用配置示例和代码片段 - 支持 L0 精确匹配的关键词
This commit is contained in:
zhuyongxin
@@ -0,0 +1,310 @@
|
||||
---
|
||||
title: Flyway 数据库迁移最佳实践
|
||||
keywords: [Flyway, 数据库迁移, 版本管理, schema, migration]
|
||||
summary: Flyway 数据库迁移的命名规范、编写技巧、回滚策略和常见问题处理
|
||||
category: infrastructure
|
||||
---
|
||||
|
||||
# Flyway 数据库迁移最佳实践
|
||||
|
||||
## 命名规范
|
||||
|
||||
### 标准格式
|
||||
```
|
||||
V{version}__{description}.sql
|
||||
|
||||
示例：
|
||||
V001__create_user_table.sql
|
||||
V002__add_email_to_user.sql
|
||||
V003__create_order_table.sql
|
||||
V004__add_metadata_to_api_document.sql
|
||||
```
|
||||
|
||||
**规则**：
|
||||
- `V` 大写，表示 Versioned migration
|
||||
- 版本号用 3 位数字（001, 002...）
|
||||
- 两个下划线 `__` 分隔版本号和描述
|
||||
- 描述用小写字母和下划线
|
||||
|
||||
### 版本号管理
|
||||
```
|
||||
V001 - 初始表结构
|
||||
V002 - 添加字段
|
||||
V003 - 创建索引
|
||||
V004 - 修改字段类型
|
||||
...
|
||||
```
|
||||
|
||||
**建议**：
|
||||
- 预留版本号空间（001, 010, 020...）
|
||||
- 紧急修复用中间号（V005_hotfix__...）
|
||||
|
||||
## SQL 编写规范
|
||||
|
||||
### 添加列
|
||||
```sql
|
||||
-- ✅ 好的写法 - 包含默认值和注释
|
||||
ALTER TABLE user
|
||||
ADD COLUMN email VARCHAR(100) DEFAULT '' COMMENT '用户邮箱';
|
||||
|
||||
-- ❌ 不好的写法 - 缺少默认值
|
||||
ALTER TABLE user
|
||||
ADD COLUMN email VARCHAR(100); -- 已有数据会是 NULL
|
||||
```
|
||||
|
||||
### 修改列
|
||||
```sql
|
||||
-- ✅ 先添加新列，再迁移数据，最后删除旧列
|
||||
ALTER TABLE user ADD COLUMN new_status VARCHAR(20) DEFAULT 'active';
|
||||
UPDATE user SET new_status = old_status WHERE old_status IS NOT NULL;
|
||||
ALTER TABLE user DROP COLUMN old_status;
|
||||
ALTER TABLE user CHANGE COLUMN new_status status VARCHAR(20);
|
||||
|
||||
-- ❌ 直接修改 - 可能导致数据丢失
|
||||
ALTER TABLE user MODIFY COLUMN status INT;
|
||||
```
|
||||
|
||||
### 创建索引
|
||||
```sql
|
||||
-- ✅ 指定索引名称
|
||||
CREATE INDEX idx_user_email ON user(email);
|
||||
CREATE INDEX idx_order_user_id ON `order`(user_id);
|
||||
|
||||
-- ❌ 不指定名称 - 自动生成的名称难以管理
|
||||
CREATE INDEX ON user(email);
|
||||
```
|
||||
|
||||
### 外键约束
|
||||
```sql
|
||||
-- ✅ 命名规范
|
||||
ALTER TABLE `order`
|
||||
ADD CONSTRAINT fk_order_user_id
|
||||
FOREIGN KEY (user_id) REFERENCES user(id)
|
||||
ON DELETE CASCADE;
|
||||
|
||||
-- ❌ 不指定名称
|
||||
ALTER TABLE `order`
|
||||
ADD FOREIGN KEY (user_id) REFERENCES user(id);
|
||||
```
|
||||
|
||||
## 幂等性保证
|
||||
|
||||
### 检查表是否存在
|
||||
```sql
|
||||
-- 创建表前检查
|
||||
CREATE TABLE IF NOT EXISTS user (
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
username VARCHAR(50) NOT NULL
|
||||
);
|
||||
```
|
||||
|
||||
### 检查列是否存在
|
||||
```sql
|
||||
-- 添加列前检查
|
||||
ALTER TABLE user
|
||||
ADD COLUMN IF NOT EXISTS email VARCHAR(100);
|
||||
|
||||
-- 或使用存储过程（MySQL < 8.0）
|
||||
SET @col_exists = (
|
||||
SELECT COUNT(*) FROM information_schema.columns
|
||||
WHERE table_name = 'user' AND column_name = 'email'
|
||||
);
|
||||
|
||||
SET @query = IF(@col_exists = 0,
|
||||
'ALTER TABLE user ADD COLUMN email VARCHAR(100)',
|
||||
'SELECT "Column exists" AS msg'
|
||||
);
|
||||
|
||||
PREPARE stmt FROM @query;
|
||||
EXECUTE stmt;
|
||||
DEALLOCATE PREPARE stmt;
|
||||
```
|
||||
|
||||
### 检查索引是否存在
|
||||
```sql
|
||||
CREATE INDEX IF NOT EXISTS idx_user_email ON user(email);
|
||||
```
|
||||
|
||||
## 数据迁移
|
||||
|
||||
### 分批处理大表
|
||||
```sql
|
||||
-- ❌ 一次更新全部 - 可能锁表很久
|
||||
UPDATE large_table SET status = 'active' WHERE status IS NULL;
|
||||
|
||||
-- ✅ 分批更新
|
||||
UPDATE large_table
|
||||
SET status = 'active'
|
||||
WHERE status IS NULL
|
||||
LIMIT 1000;
|
||||
|
||||
-- 重复执行直到影响行数为 0
|
||||
```
|
||||
|
||||
### 使用事务（DDL 语句除外）
|
||||
```sql
|
||||
START TRANSACTION;
|
||||
|
||||
UPDATE user SET status = 'active' WHERE status = 'enabled';
|
||||
UPDATE user SET status = 'inactive' WHERE status = 'disabled';
|
||||
|
||||
COMMIT;
|
||||
```
|
||||
|
||||
## 回滚策略
|
||||
|
||||
### 不支持自动回滚
|
||||
Flyway 社区版不支持自动回滚，需要手动编写撤销脚本：
|
||||
|
||||
```sql
|
||||
-- V005__add_email_to_user.sql
|
||||
ALTER TABLE user ADD COLUMN email VARCHAR(100);
|
||||
|
||||
-- V005__add_email_to_user.undo.sql (手动执行)
|
||||
ALTER TABLE user DROP COLUMN email;
|
||||
```
|
||||
|
||||
### 建议使用新版本修复
|
||||
```sql
|
||||
-- V005 出错了，不要回滚
|
||||
-- 而是创建 V006 修复
|
||||
|
||||
-- V006__fix_user_email.sql
|
||||
ALTER TABLE user MODIFY COLUMN email VARCHAR(200);
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 问题 1: 迁移失败后状态卡住
|
||||
|
||||
**症状**：
|
||||
```
|
||||
FlywayException: Migration failed!
|
||||
Schema history table shows failed migration.
|
||||
```
|
||||
|
||||
**解决**：
|
||||
```sql
|
||||
-- 查看迁移历史
|
||||
SELECT * FROM flyway_schema_history ORDER BY installed_rank DESC;
|
||||
|
||||
-- 删除失败记录
|
||||
DELETE FROM flyway_schema_history WHERE version = '005' AND success = 0;
|
||||
|
||||
-- 修复 SQL 脚本后重新启动
|
||||
```
|
||||
|
||||
### 问题 2: Checksum 不匹配
|
||||
|
||||
**症状**：
|
||||
```
|
||||
FlywayException: Checksum mismatch for migration version 005
|
||||
```
|
||||
|
||||
**原因**：迁移脚本被修改了
|
||||
|
||||
**解决**：
|
||||
```sql
|
||||
-- 方案 1: 修复 checksum（仅开发环境）
|
||||
UPDATE flyway_schema_history
|
||||
SET checksum = NULL
|
||||
WHERE version = '005';
|
||||
|
||||
-- 方案 2: 创建新版本（推荐）
|
||||
-- 不要修改已执行的迁移脚本，创建 V006
|
||||
```
|
||||
|
||||
### 问题 3: 多个开发者同时创建迁移
|
||||
|
||||
**场景**：
|
||||
- 开发者 A 创建 V005
|
||||
- 开发者 B 创建 V005
|
||||
- 冲突！
|
||||
|
||||
**预防**：
|
||||
```
|
||||
使用时间戳版本号：
|
||||
V20260624001__add_user_email.sql
|
||||
V20260624002__add_order_index.sql
|
||||
```
|
||||
|
||||
## 生产环境最佳实践
|
||||
|
||||
### 1. 先验证后应用
|
||||
```bash
|
||||
# 开发环境测试
|
||||
mvn flyway:migrate
|
||||
|
||||
# 预生产环境验证
|
||||
mvn flyway:migrate -Dflyway.url=jdbc:mysql://pre-prod-db:3306/db
|
||||
|
||||
# 生产环境应用
|
||||
mvn flyway:migrate -Dflyway.url=jdbc:mysql://prod-db:3306/db
|
||||
```
|
||||
|
||||
### 2. 备份数据库
|
||||
```bash
|
||||
# 应用迁移前备份
|
||||
mysqldump -u root -p superbiz_agent > backup_before_v005.sql
|
||||
|
||||
# 应用迁移
|
||||
mvn spring-boot:run
|
||||
|
||||
# 出问题时恢复
|
||||
mysql -u root -p superbiz_agent < backup_before_v005.sql
|
||||
```
|
||||
|
||||
### 3. 限制自动迁移
|
||||
```yaml
|
||||
# 生产环境配置
|
||||
spring:
|
||||
flyway:
|
||||
enabled: false # 禁用自动迁移
|
||||
|
||||
# 手动触发
|
||||
mvn flyway:migrate -Dspring.profiles.active=prod
|
||||
```
|
||||
|
||||
### 4. 监控迁移时间
|
||||
```sql
|
||||
SELECT version, description, type, installed_on, execution_time
|
||||
FROM flyway_schema_history
|
||||
ORDER BY installed_rank DESC
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
## 工具和命令
|
||||
|
||||
### Maven 命令
|
||||
```bash
|
||||
# 查看迁移信息
|
||||
mvn flyway:info
|
||||
|
||||
# 执行迁移
|
||||
mvn flyway:migrate
|
||||
|
||||
# 验证迁移
|
||||
mvn flyway:validate
|
||||
|
||||
# 清空数据库（危险！仅开发环境）
|
||||
mvn flyway:clean
|
||||
```
|
||||
|
||||
### 配置文件
|
||||
```yaml
|
||||
spring:
|
||||
flyway:
|
||||
enabled: true
|
||||
baseline-on-migrate: true # 已有数据库时从当前版本开始
|
||||
locations: classpath:db/migration
|
||||
table: flyway_schema_history
|
||||
validate-on-migrate: true
|
||||
```
|
||||
|
||||
## 团队协作规范
|
||||
|
||||
1. **迁移脚本不可修改**：已合并的脚本禁止修改
|
||||
2. **版本号递增**：新脚本必须比最新版本号大
|
||||
3. **命名规范统一**：遵循 `V{version}__{description}.sql`
|
||||
4. **Code Review**：迁移脚本必须经过审查
|
||||
5. **测试覆盖**：每个迁移都要测试（空库 + 有数据）
|
||||
@@ -0,0 +1,99 @@
|
||||
---
|
||||
title: MySQL 数据库连接池配置
|
||||
keywords: [MySQL, HikariCP, 连接池, 数据库, 性能优化]
|
||||
summary: MySQL 连接池的配置参数、性能调优和故障排查指南
|
||||
category: infrastructure
|
||||
---
|
||||
|
||||
# MySQL 数据库连接池配置
|
||||
|
||||
## HikariCP 配置
|
||||
|
||||
### 基础配置
|
||||
```yaml
|
||||
spring:
|
||||
datasource:
|
||||
url: jdbc:mysql://localhost:3306/superbiz_agent?useSSL=false&serverTimezone=Asia/Shanghai
|
||||
username: root
|
||||
password: password
|
||||
driver-class-name: com.mysql.cj.jdbc.Driver
|
||||
hikari:
|
||||
maximum-pool-size: 10
|
||||
minimum-idle: 5
|
||||
connection-timeout: 30000
|
||||
idle-timeout: 600000
|
||||
max-lifetime: 1800000
|
||||
```
|
||||
|
||||
## 关键参数说明
|
||||
|
||||
### maximum-pool-size
|
||||
- **默认值**：10
|
||||
- **建议值**：根据并发量调整
|
||||
- **公式**：connections = ((core_count * 2) + effective_spindle_count)
|
||||
- **注意**：不是越大越好，过大会增加数据库负担
|
||||
|
||||
### connection-timeout
|
||||
- **默认值**：30000ms (30秒)
|
||||
- **说明**：等待连接的最大时间
|
||||
- **建议**：根据业务超时要求调整
|
||||
|
||||
### idle-timeout
|
||||
- **默认值**：600000ms (10分钟)
|
||||
- **说明**：连接空闲多久后被释放
|
||||
- **建议**：小于 MySQL wait_timeout
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 连接泄漏
|
||||
|
||||
**症状**：
|
||||
- 应用无法获取数据库连接
|
||||
- 日志显示 "Connection is not available"
|
||||
|
||||
**排查**：
|
||||
```java
|
||||
// 检查是否有未关闭的连接
|
||||
try (Connection conn = dataSource.getConnection()) {
|
||||
// 使用连接
|
||||
} // 自动关闭
|
||||
```
|
||||
|
||||
**解决**：
|
||||
- 使用 try-with-resources
|
||||
- 检查事务是否正常提交/回滚
|
||||
|
||||
### wait_timeout 超时
|
||||
|
||||
**症状**：MySQL 错误 "The last packet successfully received from the server was X milliseconds ago"
|
||||
|
||||
**排查**：
|
||||
```sql
|
||||
SHOW VARIABLES LIKE 'wait_timeout';
|
||||
```
|
||||
|
||||
**解决**：
|
||||
```yaml
|
||||
hikari:
|
||||
max-lifetime: 1800000 # 小于 MySQL wait_timeout
|
||||
```
|
||||
|
||||
## 性能监控
|
||||
|
||||
### HikariCP 指标
|
||||
```java
|
||||
HikariPoolMXBean poolMXBean = hikariDataSource.getHikariPoolMXBean();
|
||||
int active = poolMXBean.getActiveConnections();
|
||||
int idle = poolMXBean.getIdleConnections();
|
||||
int total = poolMXBean.getTotalConnections();
|
||||
```
|
||||
|
||||
### 慢查询监控
|
||||
```sql
|
||||
-- 开启慢查询日志
|
||||
SET GLOBAL slow_query_log = 'ON';
|
||||
SET GLOBAL long_query_time = 2;
|
||||
|
||||
-- 查看慢查询
|
||||
SELECT * FROM mysql.slow_log ORDER BY start_time DESC LIMIT 10;
|
||||
```
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
title: Redis 缓存配置指南
|
||||
keywords: [Redis, 缓存, 配置, 连接池, 超时]
|
||||
summary: Redis 缓存的配置参数说明、连接池设置和常见问题排查
|
||||
category: infrastructure
|
||||
---
|
||||
|
||||
# Redis 缓存配置指南
|
||||
|
||||
## 基础配置
|
||||
|
||||
### 连接参数
|
||||
```yaml
|
||||
spring:
|
||||
redis:
|
||||
host: localhost
|
||||
port: 6379
|
||||
password: your_password
|
||||
database: 0
|
||||
timeout: 3000ms
|
||||
```
|
||||
|
||||
### 连接池配置
|
||||
```yaml
|
||||
spring:
|
||||
redis:
|
||||
lettuce:
|
||||
pool:
|
||||
max-active: 8
|
||||
max-idle: 8
|
||||
min-idle: 0
|
||||
max-wait: -1ms
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 超时问题排查
|
||||
|
||||
**症状**：Redis 操作超时
|
||||
|
||||
**排查步骤**：
|
||||
1. 检查网络连接：`ping redis_host`
|
||||
2. 检查 Redis 服务状态：`redis-cli ping`
|
||||
3. 查看慢查询日志：`redis-cli slowlog get 10`
|
||||
4. 检查连接池状态
|
||||
|
||||
**解决方案**：
|
||||
- 增加超时时间
|
||||
- 优化慢查询
|
||||
- 调整连接池大小
|
||||
|
||||
### 连接数过多
|
||||
|
||||
**症状**：达到 Redis 最大连接数限制
|
||||
|
||||
**排查**：
|
||||
```bash
|
||||
redis-cli info clients
|
||||
```
|
||||
|
||||
**解决**：
|
||||
- 调整 `maxclients` 参数
|
||||
- 检查连接泄漏
|
||||
- 启用连接池复用
|
||||
Reference in New Issue
Block a user