@llryiop/avatar-boot-cli 1.0.0 → 1.0.2

package/templates/.claude/skills/database-design/references//347/264/242/345/274/225/350/247/204/350/214/203.md

@@ -0,0 +1,506 @@
+# MySQL 索引规范
+
+## 一、索引设计原则
+
+### 1. 最左前缀原则
+
+联合索引按 `等值查询列 → 范围查询列 → 排序列` 顺序排列
+
+```sql
+-- ✅ 正确：等值查询在前，范围查询在后
+KEY `idx_order_status_created` (`status`, `created_at`)
+
+-- 查询可以使用索引
+WHERE status = 1 AND created_at > '2026-01-01'
+
+-- ❌ 错误：范围查询在前
+KEY `idx_order_created_status` (`created_at`, `status`)
+
+-- 查询只能使用 created_at，status 无法使用索引
+WHERE status = 1 AND created_at > '2026-01-01'
+```
+
+### 2. 覆盖索引优先
+
+高频查询尽量通过覆盖索引避免回表
+
+```sql
+-- 查询：SELECT id, role_code, role_name FROM role WHERE role_code = 'ADMIN'
+
+-- ✅ 覆盖索引（包含查询所需的所有字段）
+KEY `idx_role_code_name` (`role_code`, `role_name`)
+
+-- ❌ 普通索引（需要回表查询 role_name）
+KEY `idx_role_code` (`role_code`)
+```
+
+### 3. 区分度优先
+
+优先对区分度高的列建索引
+
+**区分度计算**：`区分度 = 不重复值数 / 总行数`
+
+```sql
+-- 检查字段区分度
+SELECT
+  COUNT(DISTINCT role_code) / COUNT(*) AS code_selectivity,
+  COUNT(DISTINCT is_enabled) / COUNT(*) AS enabled_selectivity
+FROM zz_plt_role;
+
+-- 结果示例：
+-- code_selectivity: 0.95 （高区分度，适合建索引）
+-- enabled_selectivity: 0.02 （低区分度，不适合建索引）
+```
+
+### 4. 控制数量
+
+- 单表索引不超过 **5 个**
+- 联合索引字段不超过 **3 个**
+
+---
+
+## 二、必须建索引的场景
+
+### 1. 主键（自动创建）
+
+```sql
+PRIMARY KEY (`id`)
+```
+
+### 2. 唯一约束字段
+
+```sql
+-- 编码字段
+UNIQUE KEY `uk_zz_plt_role_code` (`role_code`)
+
+-- 邮箱字段
+UNIQUE KEY `uk_zz_plt_user_email` (`email`)
+```
+
+### 3. 频繁出现在 WHERE 中的字段
+
+```sql
+-- 状态字段
+KEY `idx_zz_plt_order_status` (`status`)
+
+-- 类型字段
+KEY `idx_zz_plt_avatar_type` (`avatar_type`)
+```
+
+### 4. 频繁出现在 JOIN ON 中的字段
+
+```sql
+-- 外键字段
+KEY `idx_zz_plt_order_user_id` (`user_id`)
+KEY `idx_zz_plt_order_product_id` (`product_id`)
+```
+
+### 5. 频繁出现在 ORDER BY 中的字段
+
+```sql
+-- 排序字段
+KEY `idx_zz_plt_role_sort_order` (`sort_order`)
+
+-- 创建时间（常用于排序）
+KEY `idx_zz_plt_article_created` (`created_at`)
+```
+
+---
+
+## 三、禁止建索引的场景
+
+### 1. 区分度极低的字段
+
+```sql
+-- ❌ 错误：is_deleted 只有 0 和 1 两个值
+KEY `idx_zz_plt_role_deleted` (`is_deleted`)
+
+-- ❌ 错误：gender 只有几个值
+KEY `idx_zz_plt_user_gender` (`gender`)
+
+-- ✅ 正确：可以作为联合索引的一部分
+KEY `idx_zz_plt_role_status` (`status`, `is_deleted`)
+```
+
+### 2. 频繁更新的字段
+
+```sql
+-- ❌ 错误：访问次数频繁更新，写放大严重
+KEY `idx_zz_plt_article_view_count` (`view_count`)
+
+-- ✅ 正确：如果必须查询，考虑使用其他方案（如缓存）
+```
+
+### 3. 超长字符串字段
+
+```sql
+-- ❌ 错误：全文索引在长文本上效率低
+KEY `idx_zz_plt_article_content` (`content`)
+
+-- ✅ 正确：使用前缀索引或全文索引
+KEY `idx_zz_plt_article_title` (`title`(50))  -- 前缀索引
+FULLTEXT KEY `ft_zz_plt_article_content` (`content`)  -- 全文索引
+```
+
+---
+
+## 四、索引命名规范
+
+| 类型 | 格式 | 示例 |
+|------|------|------|
+| 主键 | `pk_{表名}` | `pk_zz_plt_role` |
+| 唯一索引 | `uk_{表名}_{字段}` | `uk_zz_plt_role_code` |
+| 普通索引 | `idx_{表名}_{字段}` | `idx_zz_plt_role_name` |
+| 联合索引 | `idx_{表名}_{字段1}_{字段2}` | `idx_zz_plt_role_status_enabled` |
+| 全文索引 | `ft_{表名}_{字段}` | `ft_zz_plt_article_title` |
+
+### 注意事项
+
+- 主键索引由 MySQL 自动创建，无需在 CREATE TABLE 中显式声明
+- 索引名称要简洁明了，能清晰表达索引的用途
+- 联合索引名称按字段顺序命名
+
+---
+
+## 五、常用索引模板
+
+### 1. 唯一索引（编码字段）
+
+```sql
+UNIQUE KEY `uk_{表名}_code` (`{entity}_code`)
+
+-- 示例
+UNIQUE KEY `uk_zz_plt_role_code` (`role_code`)
+```
+
+### 2. 普通索引（名称字段）
+
+```sql
+KEY `idx_{表名}_name` (`{entity}_name`)
+
+-- 示例
+KEY `idx_zz_plt_role_name` (`role_name`)
+```
+
+### 3. 联合索引（租户+删除标记）
+
+```sql
+KEY `idx_{表名}_tenant` (`tenant_id`, `is_deleted`)
+
+-- 示例
+KEY `idx_zz_plt_role_tenant` (`tenant_id`, `is_deleted`)
+```
+
+### 4. 联合索引（状态+启用+删除）
+
+```sql
+KEY `idx_{表名}_status` (`status`, `is_enabled`, `is_deleted`)
+
+-- 示例
+KEY `idx_zz_plt_order_status` (`status`, `is_enabled`, `is_deleted`)
+```
+
+### 5. 联合索引（类型+启用+删除）
+
+```sql
+KEY `idx_{表名}_type` (`type`, `is_enabled`, `is_deleted`)
+
+-- 示例
+KEY `idx_zz_plt_avatar_type` (`avatar_type`, `is_enabled`, `is_deleted`)
+```
+
+### 6. 外键索引
+
+```sql
+KEY `idx_{表名}_{外键字段}` (`{entity}_id`)
+
+-- 示例
+KEY `idx_zz_plt_order_user_id` (`user_id`)
+KEY `idx_zz_plt_order_product_id` (`product_id`)
+```
+
+### 7. 时间索引
+
+```sql
+KEY `idx_{表名}_created` (`created_at`)
+
+-- 示例
+KEY `idx_zz_plt_article_created` (`created_at`)
+```
+
+---
+
+## 六、联合索引设计
+
+### 最左前缀原则
+
+联合索引 `(a, b, c)` 可以支持以下查询：
+
+```sql
+-- ✅ 可以使用索引
+WHERE a = 1
+WHERE a = 1 AND b = 2
+WHERE a = 1 AND b = 2 AND c = 3
+WHERE a = 1 AND c = 3  -- 只能使用 a
+
+-- ❌ 无法使用索引
+WHERE b = 2
+WHERE c = 3
+WHERE b = 2 AND c = 3
+```
+
+### 字段顺序选择
+
+1. **等值查询字段在前**
+2. **范围查询字段在后**
+3. **排序字段最后**
+
+```sql
+-- ✅ 正确顺序
+KEY `idx_order_status_created` (`status`, `created_at`)
+
+-- 查询：WHERE status = 1 AND created_at > '2026-01-01' ORDER BY created_at
+-- 可以完全使用索引
+
+-- ❌ 错误顺序
+KEY `idx_order_created_status` (`created_at`, `status`)
+
+-- 查询：WHERE status = 1 AND created_at > '2026-01-01'
+-- 只能使用 created_at，status 无法使用索引
+```
+
+### 覆盖索引设计
+
+```sql
+-- 查询：SELECT id, user_id, status, amount FROM orders WHERE user_id = 1 AND status = 1
+
+-- ✅ 覆盖索引（包含所有查询字段）
+KEY `idx_order_user_status_amount` (`user_id`, `status`, `amount`)
+
+-- 无需回表，直接从索引获取所有数据
+```
+
+---
+
+## 七、关联表索引设计
+
+关联表（中间表）必须包含：
+
+1. **联合唯一索引**（防止重复关联）
+2. **外键字段的普通索引**（提升查询性能）
+
+```sql
+CREATE TABLE `zz_plt_avatar_role_rel` (
+  `id`          BIGINT UNSIGNED  NOT NULL AUTO_INCREMENT COMMENT '主键ID',
+  `avatar_id`   BIGINT UNSIGNED  NOT NULL COMMENT '虚拟人ID',
+  `role_id`     BIGINT UNSIGNED  NOT NULL COMMENT '角色ID',
+  `created_at`  DATETIME         NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
+  `is_deleted`  TINYINT(1)       NOT NULL DEFAULT 0 COMMENT '逻辑删除：0-未删除，1-已删除',
+  PRIMARY KEY (`id`),
+  -- 联合唯一索引（防止重复关联）
+  UNIQUE KEY `uk_zz_plt_avatar_role_rel` (`avatar_id`, `role_id`),
+  -- 外键索引（提升反向查询性能）
+  KEY `idx_zz_plt_avatar_role_rel_role` (`role_id`)
+) ENGINE=InnoDB;
+```
+
+### 为什么需要两个索引？
+
+```sql
+-- 查询 1：根据 avatar_id 查询关联的 role_id
+SELECT role_id FROM zz_plt_avatar_role_rel WHERE avatar_id = 1;
+-- 使用联合唯一索引 uk_zz_plt_avatar_role_rel
+
+-- 查询 2：根据 role_id 查询关联的 avatar_id
+SELECT avatar_id FROM zz_plt_avatar_role_rel WHERE role_id = 1;
+-- 使用普通索引 idx_zz_plt_avatar_role_rel_role
+```
+
+---
+
+## 八、索引使用检查
+
+### 1. 查看索引使用情况
+
+```sql
+-- 查看执行计划
+EXPLAIN SELECT * FROM zz_plt_role WHERE role_code = 'ADMIN';
+
+-- 关键字段：
+-- type: 索引类型（const > eq_ref > ref > range > index > ALL）
+-- key: 实际使用的索引
+-- rows: 扫描的行数
+```
+
+### 2. 检查未使用的索引
+
+```sql
+-- 检查未使用的索引（定期执行）
+SELECT
+  object_schema AS `database`,
+  object_name AS `table`,
+  index_name AS `index`,
+  count_read AS `read_count`
+FROM performance_schema.table_io_waits_summary_by_index_usage
+WHERE index_name IS NOT NULL
+  AND count_read = 0
+  AND object_schema = 'your_database'
+ORDER BY object_schema, object_name;
+```
+
+### 3. 检查重复索引
+
+```sql
+-- 检查重复索引
+SELECT
+  a.table_schema,
+  a.table_name,
+  a.index_name AS index1,
+  b.index_name AS index2,
+  a.column_name
+FROM information_schema.statistics a
+JOIN information_schema.statistics b
+  ON a.table_schema = b.table_schema
+  AND a.table_name = b.table_name
+  AND a.column_name = b.column_name
+  AND a.seq_in_index = b.seq_in_index
+  AND a.index_name != b.index_name
+WHERE a.table_schema = 'your_database'
+ORDER BY a.table_name, a.index_name;
+```
+
+---
+
+## 九、索引优化建议
+
+### 1. 避免索引失效
+
+```sql
+-- ❌ 在索引列上使用函数
+WHERE DATE(created_at) = '2026-03-19'
+
+-- ✅ 改写查询
+WHERE created_at >= '2026-03-19 00:00:00' AND created_at < '2026-03-20 00:00:00'
+
+-- ❌ 隐式类型转换
+WHERE user_id = '12345'  -- user_id 是 BIGINT
+
+-- ✅ 使用正确类型
+WHERE user_id = 12345
+
+-- ❌ 前缀模糊查询
+WHERE role_name LIKE '%管理%'
+
+-- ✅ 使用全文索引或 Elasticsearch
+FULLTEXT KEY `ft_role_name` (`role_name`)
+```
+
+### 2. 合理使用前缀索引
+
+```sql
+-- 长字符串字段使用前缀索引
+KEY `idx_article_title` (`title`(50))
+
+-- 检查前缀长度的区分度
+SELECT
+  COUNT(DISTINCT LEFT(title, 10)) / COUNT(*) AS len_10,
+  COUNT(DISTINCT LEFT(title, 20)) / COUNT(*) AS len_20,
+  COUNT(DISTINCT LEFT(title, 50)) / COUNT(*) AS len_50,
+  COUNT(DISTINCT title) / COUNT(*) AS full_len
+FROM zz_plt_article;
+```
+
+### 3. 定期维护索引
+
+```sql
+-- 分析表（更新索引统计信息）
+ANALYZE TABLE zz_plt_role;
+
+-- 优化表（重建索引）
+OPTIMIZE TABLE zz_plt_role;
+```
+
+---
+
+## 十、索引设计检查清单
+
+创建索引前，请检查以下项目：
+
+- [ ] 索引名称是否符合命名规范
+- [ ] 是否避免在低区分度字段上建索引
+- [ ] 联合索引字段顺序是否合理（等值 → 范围 → 排序）
+- [ ] 是否考虑了覆盖索引优化
+- [ ] 单表索引数量是否超过 5 个
+- [ ] 联合索引字段数量是否超过 3 个
+- [ ] 是否有重复或冗余的索引
+- [ ] 关联表是否包含必要的索引
+
+---
+
+## 十一、常见错误示例
+
+### 错误 1：在低区分度字段上建索引
+
+```sql
+-- ❌ 错误
+KEY `idx_role_deleted` (`is_deleted`)  -- 只有 0 和 1 两个值
+
+-- ✅ 正确：作为联合索引的一部分
+KEY `idx_role_status` (`status`, `is_deleted`)
+```
+
+### 错误 2：联合索引字段顺序错误
+
+```sql
+-- ❌ 错误：范围查询在前
+KEY `idx_order_created_status` (`created_at`, `status`)
+
+-- ✅ 正确：等值查询在前
+KEY `idx_order_status_created` (`status`, `created_at`)
+```
+
+### 错误 3：索引过多
+
+```sql
+-- ❌ 错误：单表索引过多（7 个）
+KEY `idx_role_code` (`role_code`)
+KEY `idx_role_name` (`role_name`)
+KEY `idx_role_status` (`status`)
+KEY `idx_role_type` (`type`)
+KEY `idx_role_created` (`created_at`)
+KEY `idx_role_updated` (`updated_at`)
+KEY `idx_role_deleted` (`is_deleted`)
+
+-- ✅ 正确：合并为联合索引
+UNIQUE KEY `uk_role_code` (`role_code`)
+KEY `idx_role_name` (`role_name`)
+KEY `idx_role_status` (`status`, `type`, `is_deleted`)
+KEY `idx_role_created` (`created_at`)
+```
+
+### 错误 4：缺少关联表索引
+
+```sql
+-- ❌ 错误：只有联合唯一索引
+CREATE TABLE `zz_plt_avatar_role_rel` (
+  `id`          BIGINT UNSIGNED  NOT NULL AUTO_INCREMENT,
+  `avatar_id`   BIGINT UNSIGNED  NOT NULL,
+  `role_id`     BIGINT UNSIGNED  NOT NULL,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_avatar_role` (`avatar_id`, `role_id`)
+);
+
+-- ✅ 正确：增加反向查询索引
+CREATE TABLE `zz_plt_avatar_role_rel` (
+  `id`          BIGINT UNSIGNED  NOT NULL AUTO_INCREMENT,
+  `avatar_id`   BIGINT UNSIGNED  NOT NULL,
+  `role_id`     BIGINT UNSIGNED  NOT NULL,
+  PRIMARY KEY (`id`),
+  UNIQUE KEY `uk_avatar_role` (`avatar_id`, `role_id`),
+  KEY `idx_avatar_role_rel_role` (`role_id`)  -- 反向查询索引
+);
+```
+
+---
+
+**参考文档**：[MySQL 数据库规范](../../../database/mysql-specification.md)