AI时代的通用设计规范 适合PHP、MYSQL

作者: 时间: 2026-08-17 评论: 暂无评论
# 设计规范(PHP + MySQL)

> 通用设计规范:适用于基于 PHP(现代框架,如 Hyperf / Laravel / Symfony)与 MySQL 的后端服务。
> 规范级别约定:**[必须]** 强制要求,代码评审不通过项;**[应该]** 推荐做法,默认遵循;**[建议]** 可选优化。
> 提交评审前,代码必须通过本规范全部 **[必须]** 项与已适用的 **[应该]** 项。

## 适用范围

- 本规范适用于以下场景,必须触发自检:
  - 新建表、修改表结构、设计库表时
  - 编写或优化 SQL(查询 / 插入 / 更新 / 分页)时
  - 生成 migration 脚本时
- 不适用于 PostgreSQL / MongoDB / Redis 等非 MySQL 场景

---

## 1. PHP 规范

### 1.1 语言与环境

- **[必须]** 使用受支持的 PHP 版本(≥ 8.1),每个文件首行声明 `declare(strict_types=1);`
- **[必须]** 使用 Composer 管理依赖并提交 `composer.lock`,环境构建基于锁文件,保证可复现
- **[必须]** 全项目统一时区(`date.timezone`),避免时区错位导致的时间类缺陷
- **[必须]** 使用框架能力(路由、ORM、容器、中间件、事件、队列)解决问题,不重复造轮子
- **[应该]** 业务代码中不使用全局变量、`$_GET/$_POST` 直接取值,统一经框架 Request 抽象
- **[应该]** 代码静态检查(phpstan / psalm 等)纳入 CI

### 1.2 编码风格与命名

- **[必须]** 遵循 PSR-12 编码风格
- **[必须]** 命名规则:
  - 类 / 接口 / Trait:`PascalCase`;接口后缀 `Interface`,抽象类前缀 `Abstract`
  - 方法 / 函数 / 变量 / 属性:`camelCase`
  - 常量(类常量 / 全局常量):`SCREAMING_SNAKE_CASE`
  - 布尔变量:`is` / `has` / `can` 语义前缀(如 `isLocked` / `hasToken` / `canDelete`)
  - 私有/受保护成员:无下划线前缀,用可见性关键字表达
- **[必须]** 类文件遵循 PSR-4 自动加载;一个文件只声明一个类
- **[必须]** 方法必须有参数类型与返回类型声明;可空类型用 `?type`;联合类型用 `type1|type2`
- **[必须]** 常量集中定义(业务阈值、TTL、状态值),禁止散落魔法数字
- **[应该]** 注释只解释「为什么」,不赘述「做了什么」;逻辑复杂处必须写注释说明意图
- **[必须]** 注释 / 文档描述必须与代码实际行为一致(如声称「加密存储」就必须真的加密)

### 1.3 分层架构

- **[必须]** 三层职责分离:`Controller → Service → Model`,依赖方向单向、不得跨层

  | 层 | 职责 | 禁止 |
  |---|---|---|
  | Controller | 参数接收、格式校验、调用 Service、统一响应 | 业务逻辑、SQL |
  | Service | 业务规则、流程编排、事务边界、审计 | SQL 细节、请求/响应对象污染 |
  | Model | 表映射、关系、查询作用域、类型转换 | 业务规则 |
- **[必须]** Controller 内禁止出现 SQL、循环、复杂条件分支;只做「取参 → 校验 → 调用 → 响应」
- **[必须]** 一个方法只做一件事,方法体超过约 60 行应拆分
- **[应该]** 相同实体聚合在同一 Service,禁止散落多处修改同一表

### 1.4 依赖注入

- **[必须]** 依赖通过构造函数注入,禁止在方法内部 `new` 核心服务、禁止静态方法承载业务逻辑
- **[必须]** 禁止在业务代码中直接使用服务容器全局访问(服务定位器反模式)
- **[应该]** 面向接口编程:核心依赖定义接口,实现可替换(便于 Mock 与测试)

### 1.5 输入校验

- **[必须]** 先校验、后处理:所有外部输入(请求体、查询参数、请求头、上传文件)先过校验再进入业务
- **[必须]** 使用白名单校验(格式、长度、枚举),校验失败返回语义化错误,不进入业务逻辑
- **[必须]** 对所有字符串输入做 `trim` 与类型强转,保证后续比较的类型一致
- **[必须]** 枚举类输入(如验证码用途、登录方式)必须限定合法取值集合
- **[应该]** 复杂校验抽为校验器/表单请求对象,避免散落在 Controller 各处

### 1.6 异常与错误处理

- **[必须]** 业务异常统一继承自定义异常基类,携带错误码与用户可读消息;禁止直接抛裸 `\Exception`
- **[必须]** HTTP 状态码语义化:

  | 状态码 | 语义 |
  |---|---|
  | 400 | 参数错误 / 校验失败 |
  | 401 | 未认证 / 凭证无效 |
  | 403 | 无权限(含演示功能开关未开启) |
  | 404 | 资源不存在 |
  | 409 | 冲突(唯一性、重复操作) |
  | 419 | CSRF 校验失败 |
  | 422 | 语义 / 业务规则不满足 |
  | 423 | 资源被锁定(账号锁定) |
  | 429 | 限流 / 频控 |

- **[必须]** 全局异常处理器兜底:5xx 响应禁止返回堆栈、SQL、框架内部信息;异常详情只进服务端日志
- **[必须]** 未匹配路由返回 JSON 404,不返回框架默认 HTML 页面
- **[必须]** 禁止 `die` / `exit` / 裸 `@` 抑制错误;禁止空 `catch` 吞异常(必须记录日志或重新抛出)
- **[必须]** 日志分级正确(debug/info/warn/error),禁止把密码、令牌、验证码等敏感信息写入日志

### 1.7 安全编码

- **[必须]** 数据库访问一律走 ORM / 参数绑定,禁止字符串拼接 SQL
- **[必须]** 密码使用 bcrypt(cost ≥ 12)或 argon2 哈希,禁止明文、MD5、SHA1
- **[必须]** 验证码、令牌等一次性凭证:服务端生成 `random_bytes`/`random_int`,只存哈希(加盐),比较用 `hash_equals`(防时序攻击),设有效期、次数上限、一次性使用
- **[必须]** 登录失败返回统一文案,不泄露账号是否存在(防用户枚举)
- **[必须]** 写操作必须防 CSRF(双提交令牌或同源校验),比较用常数时间函数
- **[必须]** 认证令牌:短时效 Access + 可吊销、轮换的 Refresh;令牌存 httpOnly Cookie(SameSite),响应与日志中不得出现明文令牌
- **[必须]** 设备/会话维度支持吊销,吊销后相关令牌立即失效
- **[必须]** 上传文件:扩展名 + MIME 白名单、大小上限、内容魔数校验、服务端生成随机文件名、存储目录不可执行脚本
- **[必须]** 密码、私钥、盐、第三方凭证必须来自环境变量/配置中心,禁止硬编码;禁止使用默认密钥上线
- **[必须]** 敏感个人信息(证件号、银行卡号,手机号等)明文落库,接口只返回脱敏值
- **[必须]** 手机号全库统一「区号 + 号码」两段式:`country_code VARCHAR(8)`(E.164 格式,如 `+86`)+ `phone VARCHAR(20)`(号码本体,不含 `+`),禁止把区号拼进号码列
- **[应该]** 登录等敏感路径全量写审计日志(成功/失败、原因、IP、UA、设备),审计记录只追加、不修改不删除

### 1.8 并发与事务

- **[必须]** 计数累加 / 状态流转等读改写操作必须原子化:优先 SQL 原子更新(`SET x = x + 1`)或带条件更新,禁止纯「读-改-写」三段式(并发丢失更新)
- **[必须]** 业务唯一性由数据库唯一约束兜底,代码只做友好提示,禁止仅靠「先查后插」保证唯一
- **[必须]** 一次性资源(验证码、二维码票据、兑换码)的「领取/作废」必须原子(条件更新或加锁),防止并发重复消费
- **[必须]** 事务保持短小:事务内禁止远程调用(HTTP、短信、邮件)与长查询;事务边界清晰,只包裹需要一致性的写操作
- **[应该]** 高频读写热点按场景选择乐观锁(版本号)或悲观锁(行锁 `FOR UPDATE`),避免表锁
- **[应该]** 对外写接口设计幂等键,重复请求不产生重复副作用

### 1.9 性能

- **[必须]** 查询避免 N+1:关联数据使用预加载
- **[必须]** 列表/分页接口必须有数量上限(`per_page` 上下限兜底),禁止无界查询
- **[必须]** 禁止循环内查询数据库 / 循环内发远程请求
- **[必须]** 大量数据写入使用批量插入,避免逐条 insert
- **[应该]** 高频只读数据使用缓存,并明确缓存失效与一致性策略

### 1.10 配置与环境

- **[必须]** 配置分层(dev / test / prod),敏感配置不入版本库(提供 `.env.example` 模板)
- **[必须]** 生产环境必须关闭调试开关(DEBUG、验证码明文回显、演示查询接口等),且此类开关要有运行时门禁(开启才可用,关闭必须 403/404)
- **[必须]** 配置值使用前做类型强转,避免字符串/布尔歧义

### 1.11 测试

- **[必须]** 认证、支付、权限等关键流程必须有自动化测试(单元 / 集成 / e2e)
- **[应该]** 测试覆盖:正常路径、边界条件(空值、超长、越界)、异常路径、并发竞态
- **[应该]** 修复 bug 时先补回归测试

---

## 2. MySQL 规范

### 2.1 存储引擎与字符集

- **[必须]** 统一 InnoDB(事务 + 行锁 + 崩溃恢复)
- **[必须]** 统一字符集 `utf8mb4`;MySQL 8 采用排序规则 `utf8mb4_0900_ai_ci`(MySQL 5.7 采用 `utf8mb4_unicode_520_ci`)
- **[必须]** 建表语句必须带 `ENGINE=InnoDB` 与 `COMMENT`,每个字段必须有 `COMMENT` 说明业务含义
- **[必须]** 禁止使用外键与级联:高并发下外键强阻塞、易引发更新风暴,约束由应用层保证
- **[必须]** 禁止用存储过程、触发器、视图承载核心业务逻辑(逻辑必须写在应用层)
- **[必须]** 大表 DDL 必须用在线变更工具(`gh-ost` / `pt-online-schema-change`),禁止直接 ALTER 大表;小表 DDL 用 `ALGORITHM=INPLACE`
- **[必须]** 时间字段一律用**正整数整数时间戳**存储:默认 `BIGINT UNSIGNED` 存 Unix 秒(UTC);`created_at` / `updated_at` 固定为秒级,其余时间字段在业务要求毫秒精度时,可用 `BIGINT UNSIGNED` 存 Unix 毫秒(列名不加后缀);每个字段的秒 / 毫秒语义确定后固定不变,跨字段比较时注意单位一致;展示时由应用层转换时区;禁止 `DATETIME` / `TIMESTAMP` / `DATE` / 字符串(杜绝时区语义分歧);纯日期场景(如生日)同样用时间戳表达

### 2.2 表设计

- **[必须]** 每表必须有主键:`id INT UNSIGNED AUTO_INCREMENT`(默认);预计行数接近 21 亿(signed INT 上限,保守阈值)的高增长表(如 message 消息表)使用 `id BIGINT UNSIGNED AUTO_INCREMENT`;主键仅 `id` 单字段;禁止 UUID / 字符串 / 业务唯一键替代主键(索引膨胀、耦合业务),业务唯一键一律用唯一索引表达;分布式强需求使用 UUID 主键须评审特批
- **[必须]** 每表必备三字段:
  - `id`(主键)
  - `created_at BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '创建时间(Unix 秒,0 表示未设置)'`
  - `updated_at BIGINT UNSIGNED NOT NULL DEFAULT 0 COMMENT '更新时间(Unix 秒,应用层维护,0 表示未设置)'`
  - 命名全库统一,禁止混用 `create_time` / `update_time` 等其他写法
  - 全库时间统一为**正整数 Unix 时间戳(`BIGINT UNSIGNED`)**:默认秒级(`0` 表示未设置);`created_at` / `updated_at` 固定秒级,其余时间字段业务要求毫秒精度时使用毫秒级(列名不加后缀);存储紧凑、无时区错位、比较与排序高效;展示格式化(`Y-m-d H:i:s`)在应用层完成;`updated_at` 由应用层(ORM 时间戳机制)维护,不使用 `ON UPDATE CURRENT_TIMESTAMP`
- **[必须]** 业务唯一性用唯一约束 / 唯一索引表达(`UNIQUE KEY`),并在应用层返回友好冲突提示
- **[必须]** 逻辑删除优先于物理删除:统一 `is_deleted TINYINT(1) NOT NULL DEFAULT 0`(全库唯一口径,禁止改用其他字段表达逻辑删除);须处理唯一键复用(如「手机号唯一」在记录已删除后的冲突策略)
- **[必须]** 表结构满足已声明的业务约束:如「密码绝不落明文」→ 表里只能有哈希列;「验证码哈希存储」→ 不能存在明文列
- **[必须]** 禁止将密码、令牌、验证码等凭证明文入库;敏感个人信息(证件号、银行卡号等)统一明文落库,接口只返回脱敏值
- **[必须]** 所有字段 `NOT NULL` + 合理默认值(仅业务必须可空时允许 NULL,如可选手机号)
- **[必须]** 状态字段用 `TINYINT` / `INT`(按取值范围选择)+ 应用层常量映射,取值不设上限,禁止无注释魔法值

### 2.3 命名规范

- **[必须]** 库名 / 表名 / 字段名:小写字母 + 数字 + 下划线,见名知意,**不超过 30 字符**,禁止拼音;表名用 `snake_case` 复数并带业务/模块前缀(如 `user_devices`、`login_logs`)
- **[必须]** 字段名:`snake_case`,语义完整清晰(如 `refresh_token_hash` 而非 `rtk`)
- **[必须]** 禁用 MySQL 保留字(`desc` / `range` / `match` / `key` / `order` 等),无法避免时用反引号
- **[必须]** 临时表 `tmp_xxx_YYYYMMDD`,备份表 `bak_xxx_YYYYMMDD`
- **[必须]** 索引命名:主键用 `PRIMARY KEY`;唯一索引 `uk_<字段>`、普通索引 `idx_<字段>`,跨表/多字段场景加表名缩写(如 `uk_user_phone`、`idx_user_created`)
- **[必须]** 同一字段在多表中的类型与命名必须完全一致(避免隐式转换致索引失效)
- **[应该]** 外键约束命名 `fk_<表>_<引用表>`(本规范禁用外键,此条仅约束遗留场景)

### 2.4 字段类型

- **[必须]** 按场景选择类型,禁止越权使用:

  | 场景 | 必须使用 | 禁止使用 |
  |---|---|---|
  | 布尔 | `TINYINT(1)`,取值只允许 0/1 | — |
  | 状态 / 枚举 | `TINYINT` 或 `INT`(按取值范围),取值不设上限,配应用层常量 | `ENUM` / 英文枚举值 |
  | 小整数 | `TINYINT` / `SMALLINT` | — |
  | 常规整数 | `INT` | — |
  | 主键 | `INT UNSIGNED AUTO_INCREMENT`(高增长表如 message 用 `BIGINT UNSIGNED`) | UUID / 字符串主键 |
  | 金额 / 汇率 | `DECIMAL(M,2)`,M 按业务定 | `FLOAT` / `DOUBLE`(精度丢失) |
  | 定长短字符串 | `CHAR(N)` | — |
  | 不定长字符串 | `VARCHAR(N)`,N ≤ 5000 | 一律 `VARCHAR(255)` |
  | 超长文本(商品详情等) | `TEXT` / `LONGTEXT`,拆到独立表用主键关联 | 塞进主表拖垮索引 |
  | 时间 | `BIGINT UNSIGNED`(默认 Unix 秒级;`created_at` / `updated_at` 固定秒级,其余字段业务要求毫秒精度时用 Unix 毫秒) | `DATETIME` / `TIMESTAMP` / `DATE`(本规范统一正整数 int 时间戳) |

- **[必须]** 证件号 / 银行卡号等定长数据不超必要长度,且落库不加密;**手机号两段式**:`country_code VARCHAR(8)`(E.164,如 `+86`)+ `phone VARCHAR(20)`(号码本体),唯一约束建在 `(country_code, phone)` 组合上
- **[必须]** 业务枚举值一律用 `TINYINT` / `INT`(按取值范围)+ 应用层常量映射;禁止 `ENUM` 与英文枚举值(如 `status = 'ACTIVE'`)

### 2.5 索引规范

- **[必须]** 单表索引 ≤ 5 个,单索引字段 ≤ 5 个
- **[必须]** 区分度低的列(`gender` / `status` / `is_deleted`)禁止单独建索引,可作组合索引后缀
- **[必须]** 组合索引遵循最左前缀:建立 `(a,b,c)` 即覆盖 `(a)` / `(a,b)` / `(a,b,c)`,避免重复建设
- **[必须]** WHERE / ORDER BY / GROUP BY 的字段应建索引,避免 `filesort`
- **[必须]** JOIN 列数据类型必须相同且都建索引,小表驱动大表
- **[必须]** 索引列上禁止函数运算与隐式类型转换(`WHERE DATE(created_at)=...`、字符串列查数字),会导致索引失效
- **[必须]** 唯一性约束用唯一索引,并作为并发写入的最终兜底
- **[必须]** 禁止冗余索引与重复索引(如已有 `idx(a,b)` 又建 `idx(a)`);新查询先 `EXPLAIN` 验证执行计划
- **[应该]** 大文本字段索引用前缀索引(`INDEX idx_title(title(100))`)
- **[应该]** 建索引前用 `SELECT COUNT(DISTINCT col) / COUNT(*)` 评估区分度
- **[应该]** 高频查询构造覆盖索引(`SELECT` 列包含在索引中)减少回表

### 2.6 SQL 编写规范

- **[必须]** 禁止 `SELECT *`,必须明确列出字段(减少 IO 与耦合):
-- 反例
SELECT * FROM orders WHERE user_id = 1000;
-- 正例
SELECT id, order_no, status, amount FROM orders WHERE user_id = 1000;

- **[必须]** INSERT 必须指定字段,禁止 `INSERT INTO t VALUES (...)` 无列名写法
- **[必须]** 深分页禁止 `LIMIT offset, size`,用游标分页:
-- 反例(深分页全扫)
SELECT * FROM orders ORDER BY id DESC LIMIT 1000000, 20;
-- 正例(游标)
SELECT id, order_no FROM orders WHERE id < ? ORDER BY id DESC LIMIT 20;

- **[必须]** WHERE 索引列禁止函数 / 运算:
-- 反例(索引列套函数)
WHERE YEAR(FROM_UNIXTIME(created_at)) = 2026
-- 正例(半开区间,参数绑定)
WHERE created_at >= ? AND created_at < ?   -- ? 为应用层传入的 Unix 时间戳

- **[必须]** 禁止负向查询(`!=` / `NOT IN` / `NOT LIKE`)与 `%xxx` 前缀模糊查询(致全表扫描);优先等值 / 范围查询
- **[必须]** `IN` 列表 < 1000 项,超量改用 JOIN 或临时表
- **[必须]** 禁止 `ORDER BY RAND()`;禁止大表 JOIN 大表;避免子查询(用 JOIN 替代)
- **[必须]** 时间范围统一用半开区间 `>= AND <`,禁止 `BETWEEN` / `<=`(均含右边界,边界语义易歧义)
- **[必须]** 分页 / 批量查询必须有 `LIMIT` 上限
- **[必须]** 批量插入分批执行(单批数百~数千行),避免超大 SQL
- **[必须]** 锁范围最小化(`FOR UPDATE` 只锁必要行)
- **[必须]** 统计口径明确:`COUNT` 用明确的 `COUNT(*)` 或 `COUNT(列)`;大表计数禁止无过滤全表扫
- **[应该]** 大批量数据变更(更新/删除)分片执行,避免长时间持有锁与主从延迟
- **[应该]** 复杂聚合(趋势、分布统计)明确窗口与口径,必要时用汇总表 / 缓存结果

### 2.7 数据安全与合规

- **[必须]** 数据库账号最小权限:应用账号仅授本库 DML,管理账号与业务账号分离;禁止应用使用 root
- **[必须]** 敏感数据(个人信息)统一明文落库、接口脱敏返回、设置保留期与定期清理任务
- **[必须]** 存储的个人照片、证件扫描件等设置访问控制与生命周期(到期删除),并有清理任务实现(不允许只写注释不实现)
- **[应该]** 定期备份与恢复演练;审计表等只追加表按容量规划滚动清理/归档
- **[应该]** 慢查询日志开启,定期审查慢 SQL

### 2.8 性能与运维基线

- **[应该]** 连接使用连接池;应用与数据库间开启长连接复用
- **[应该]** 大表按时间/业务维度规划分区或归档策略
- **[应该]** 上线变更(加索引、改表)在低峰执行,DDL 使用在线算法 / 在线变更工具

### 2.9 建表 / 变更 SQL 产出流程

按以下步骤执行,每步自检通过再进入下一步:

1. 与业务确认实体、字段、关系、预期数据量与查询模式
2. 按「基础 → 命名 → 字段 → 表结构 → 索引」顺序逐条自检本规范
3. 输出完整 DDL(含 COMMENT、默认值、索引、引擎、字符集)
4. 附带 migration 脚本,必须幂等(`IF NOT EXISTS` / `INSERT IGNORE`),本地验证「全新安装 + 升级安装」两条路径
5. 用 `EXPLAIN` 验证关键查询命中索引:`type` 应为 `const` / `ref` / `range`,禁止 `ALL`

---

## 3. 评审入口与提交前检查清单

代码 / DDL 提交评审时逐条核对:

- [ ] 所有表、字段有 COMMENT,注释说明业务含义
- [ ] 主键存在且为 `INT UNSIGNED AUTO_INCREMENT`(高增长表为 `BIGINT UNSIGNED`),主键仅 `id` 单字段
- [ ] `id` / `created_at` / `updated_at` 三字段齐全(时间字段为 `BIGINT UNSIGNED` 时间戳),命名全库统一
- [ ] 无外键、无冗余索引、无重复索引、无保留字
- [ ] 金额字段为 `DECIMAL`,无 `FLOAT` / `DOUBLE` 存金额
- [ ] 所有字段 `NOT NULL` 有默认值(业务必须可空除外)
- [ ] 索引区分度已评估;单表索引 ≤ 5,区分度低列未单独建索引
- [ ] 无 `SELECT *`、无字符串拼接 SQL、无深分页 `OFFSET`、无负向查询
- [ ] migration 脚本幂等且本地通过(全新安装 + 升级安装)
- [ ] 关键 SQL 已 `EXPLAIN` 验证(type 非 ALL)
- [ ] 注释 / 文档声称与实现一致(声称加密、声称即删必须真实实现)
- [ ] 唯一性由数据库约束兜底,无「先查后插」;一次性资源消费原子化
- [ ] 无明文凭证数据(密码 / 令牌 / 验证码);敏感个人信息(证件号 / 银行卡号 / 手机号)接口已脱敏返回

### 禁止做的事(红线)

- 不要生成带外键的 DDL
- 不要用 `FLOAT` / `DOUBLE` 存金额
- 不要用 `SELECT *`
- 不要用字符串列做主键
- 不要在索引列上套函数
- 不要用存储过程 / 触发器 / 视图承载核心业务逻辑
- 不要一次性给出大批量未经自检的 DDL,必须逐表自检后再输出
- 不要硬编码密钥与默认密钥上线

GO channel总结

作者: 时间: 2026-05-29 评论: 暂无评论

1. Channel 四种读取方式

1.1 直接读取(无 ok 检测)

ch := make(chan int, 1)
v := <-ch // 不会 panic,但无法区分是真实零值还是关闭后零值

1.2 带 ok 检测的读取

v, ok := <-ch
// ok 为 true 时,表示成功从 channel 读到真实数据。
// ok 为 false 时,表示 channel 已关闭且无更多数据,此时 v 是类型零值。

1.3 range 循环读取

timer := time.NewTicker(5 * time.Second)
defer timer.Stop()
for v := range timer.C{
   fmt.Println(1)
}
  • 会持续从 channel 读取值,直到 channel 被关闭且数据读完,循环自动终止。
  • 等效于不断执行 v, ok := <-ch 并检查 ok,写法更简洁。
  • 注意:如果 channel 永远不关闭,会一直阻塞造成死锁(除非有其他退出机制)。

1.4 select 多路复用读取

select {
case v := <-ch:
    // 处理数据
default:
    // 非阻塞
}

timer := time.NewTicker(5 * time.Second)
defer timer.Stop()
for {
     select {
    case <-timer.C:
      fmt.Println(1)
     }
   }
  • 可以同时监听多个 channel,哪个有数据就执行对应的 case。
  • 配合 default 可实现非阻塞读取:若所有 channel 都无数据则立即执行 default。
  • 即使某个 channel 已关闭,读取也会立即得到零值(需结合 v, ok := <-ch 检测关闭)。

Channel 状态速记

操作nil channel正常 channelclosed channel
读取阻塞正常读取返回零值
写入阻塞正常写入panic
关闭panic正常关闭panic

读关零值,写关 panic;nil 两边都阻塞;无缓冲要配对,有缓冲看容量;关两次也要 panic。


2. sync.WaitGroup 等待多 goroutine

场景:汇总多个请求并发处理。如同时对多个用户发送通知、对多个文件压缩、大量图片缩略图生成、多 API 聚合。

2.1 基础用法

package main

import (
    "fmt"
    "sync"
    "time"
)

func work(id int, wg *sync.WaitGroup) {
    defer wg.Done()
    fmt.Printf("Worker %d starting\n", id)
    time.Sleep(time.Second * 2)
    fmt.Printf("Worker %d done\n", id)
}

func main() {
    var wg sync.WaitGroup
    for i := 0; i < 10; i++ {
        wg.Add(1)
        go work(i, &wg)
    }
    wg.Wait()
    fmt.Println("ALL DONE")
}

2.2 多服务聚合(带错误处理)

package main

func AggregateData(ctx context.Context) (Result, error) {
    var wg sync.WaitGroup
    var mu sync.Mutex
    var userData *User
    var orderData *Order
    var errs []error

    wg.Add(3)

    // 调用用户服务
    go func() {
        defer wg.Done()
        data, err := callUserService(ctx)
        mu.Lock()
        userData = data
        if err != nil {
            errs = append(errs, err)
        }
        mu.Unlock()
    }()

    // 调用订单服务
    go func() {
        defer wg.Done()
        data, err := callOrderService(ctx)
        mu.Lock()
        orderData = data
        if err != nil {
            errs = append(errs, err)
        }
        mu.Unlock()
    }()

    // 调用库存服务(类似)

    wg.Wait()
    // 汇总结果或处理错误
    if len(errs) > 0 {
        return Result{}, combineErrors(errs)
    }
    return merge(userData, orderData), nil
}

3. 生产者-消费者模式(Channel 实现)

package main

import (
    "fmt"
    "math/rand"
    "strconv"
    "sync"
    "time"
)

// Order 任务结构体(模拟外卖订单)
type Order struct {
    ID       int
    Shop     string  // 店铺名
    Dish     string  // 菜品
    Distance float64 // 配送距离(km)
}

func GenOrderNo() string {
    now := time.Now().Unix()
    randNum := rand.Intn(10000)
    orderNo := fmt.Sprintf("%d%d", now, randNum)
    return orderNo
}

func main() {
    orderChan := make(chan Order, 5)

    var producerWg sync.WaitGroup
    var consumerWg sync.WaitGroup

    // 启动生产者(15个)
    for i := 1; i <= 15; i++ {
        producerWg.Add(1)
        go func(id int) {
            defer producerWg.Done()
            orderId, _ := strconv.ParseInt(GenOrderNo(), 10, 64)
            order := Order{
                ID:       int(orderId),
                Shop:     "厦门小吃店",
                Dish:     "海蛎煎",
                Distance: float64(9%3 + 1),
            }
            fmt.Printf("【生产者-%d】新订单:%d\n", id, order.ID)
            orderChan <- order
            time.Sleep(time.Millisecond * 10)
        }(i)
    }

    // 启动消费者(3个骑手)
    for i := 1; i <= 3; i++ {
        consumerWg.Add(1)
        go func(id int) {
            defer consumerWg.Done()
            for order := range orderChan {
                fmt.Printf("【骑手-%d】接到订单 %d,配送 %.1f km\n", id, order.ID, order.Distance)
                time.Sleep(time.Second * 5)
                fmt.Printf("【骑手-%d】订单 %d 已送达\n", id, order.ID)
            }
        }(i)
    }

    // 等待所有生产者完成 → 关闭 channel → 等待消费者完成
    producerWg.Wait()
    close(orderChan)
    consumerWg.Wait()

    fmt.Println("厦门外卖系统打烊啦~")
}

4. select 超时控制

package main

import (
    "context"
    "fmt"
    "time"
)

func callUserServe(ctx context.Context) (string, error) {
    timer := time.NewTimer(time.Second * 2)
    select {
    case <-timer.C:
        return "user_info", nil
    case <-ctx.Done():
        return "", ctx.Err()
    }
}

func callOrderServe(ctx context.Context) (string, error) {
    timer := time.NewTimer(time.Second * 3)
    select {
    case <-timer.C:
        return "order_info", nil
    case <-ctx.Done():
        return "", ctx.Err()
    }
}

func main() {
    type result struct {
        name string
        data string
        err  error
    }
    resultCh := make(chan result, 2)

    ctx, cancel := context.WithTimeout(context.Background(), time.Second*4)
    defer cancel()

    go func() {
        data, err := callUserServe(ctx)
        resultCh <- result{"user", data, err}
    }()

    go func() {
        data, err := callOrderServe(ctx)
        resultCh <- result{"order", data, err}
    }()

    ret := make(map[string]string)
    for i := 0; i < 2; i++ {
        select {
        case <-ctx.Done(): // 整体超时或上游取消
            fmt.Println("整体超时或上游取消!")
            return
        case res := <-resultCh:
            if res.err != nil {
                fmt.Printf("%s error: %v\n", "事务", res.err)
                return
            }
            ret[res.name] = res.data
        }
    }
    fmt.Printf("最后结果: %v\n", ret)
}

5. Worker Pool(带最大并发数控制)

package main

import (
    "fmt"
    "sync"
    "time"
)

type Task func()

type WorkPool struct {
    maxWorkers int
    taskQueue  chan Task
    wg         sync.WaitGroup
    stopOnce   sync.Once
    stop       chan struct{}
}

func NewWorkPool(maxWorker int, queueSize int) *WorkPool {
    return &WorkPool{
        maxWorkers: maxWorker,
        taskQueue:  make(chan Task, queueSize),
        stop:       make(chan struct{}),
    }
}

func (p *WorkPool) worker() {
    defer p.wg.Done()
    for {
        select {
        case task, ok := <-p.taskQueue:
            if !ok {
                return // 任务队列已关闭,worker 退出
            }
            task()
        case <-p.stop:
            return // 收到停止信号,退出
        }
    }
}

func (p *WorkPool) Start() {
    for i := 0; i < p.maxWorkers; i++ {
        p.wg.Add(1)
        go p.worker()
    }
}

func (p *WorkPool) Submit(task Task) bool {
    select {
    case <-p.stop:
        return false
    default:
    }
    select {
    case p.taskQueue <- task:
        return true
    case <-p.stop:
        return false
    }
}

// StopGracefully 优雅关闭:不再接收新任务,等待所有已提交任务完成
func (p *WorkPool) StopGracefully() {
    p.stopOnce.Do(func() {
        close(p.taskQueue)
    })
    p.wg.Wait()
}

func main() {
    pool := NewWorkPool(2, 6) // 2个协程,队列长度6
    pool.Start()

    for i := 0; i < 10; i++ {
        taskID := i
        submit := pool.Submit(func() {
            fmt.Printf("task %d 开始\n", taskID)
            time.Sleep(500 * time.Millisecond)
            fmt.Printf("任务 %d 执行完毕\n", taskID)
        })
        if !submit {
            fmt.Printf("任务 %d 提交失败,池已停止\n", taskID)
        }
    }

    pool.StopGracefully()
    fmt.Println("pool stopped")
}

6. sync.Mutex 保护计数器

package main

import (
    "fmt"
    "sync"
)

type Counter struct {
    mu    sync.RWMutex
    value int
}

func (c *Counter) Add() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.value++
}

func (c *Counter) Value() int {
    c.mu.RLock()
    defer c.mu.RUnlock()
    return c.value
}

func main() {
    var wg sync.WaitGroup
    c := &Counter{}

    for i := 0; i < 100; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            c.Add()
        }()
    }

    wg.Wait()
    fmt.Println(c.Value())
}

7. sync.RWMutex 实现读多写少的缓存

package main

import (
    "fmt"
    "sync"
)

type Counter struct {
    mu    sync.RWMutex
    value int
}

func (c *Counter) Add() {
    c.mu.Lock()
    defer c.mu.Unlock()
    c.value++
}

func (c *Counter) Value() int {
    c.mu.RLock()
    defer c.mu.RUnlock()
    return c.value
}

func main() {
    var wg sync.WaitGroup
    c := &Counter{}

    for i := 0; i < 100; i++ {
        wg.Add(1)
        go func() {
            defer wg.Done()
            c.Add()
        }()
    }

    wg.Wait()
    fmt.Println(c.Value())
}

mysql读写分离

作者: 时间: 2026-05-11 评论: 暂无评论

主从同步延迟是核心痛点
一、为什么会不同步?(延迟成因)
主从复制本质是异步:主库提交事务后立即返回客户端,从库通过 IO_THREAD 拉取 binlog 并重放(SQL_THREAD)。

延迟来源:

从库硬件差(磁盘慢、CPU弱)

主库写入压力大,binlog 产生速度超过从库重放速度

从库承担了大量复杂查询,占用资源

网络延迟

大事务(如一次删除百万行)在从库重放时阻塞

二、保证同步的方法(追求强一致)
方案 原理 优点 缺点
强制读主库 对一致性要求高的操作(如转账后立即查询余额),让代码判断路由到主库 100% 准确,无延迟 增加主库压力,无法发挥读写分离的扩展性
半同步复制 主库至少等待一个从库确认收到 binlog 后才返回客户端 基本不丢数据,延迟可控(等待一个 ack) 如果从库网络抖动,会阻塞主库写入;MySQL 5.7+ 支持 AFTER_SYNC 模式
组复制(MGR) 基于 Paxos,所有节点同步写入,强一致 真正强一致,自动故障切换 性能下降(写放大),只适合写少读多场景
等待从库位点 写入后,查询前检查从库的 Seconds_Behind_Master 或 binlog 位点,等它追上 应用层可控 增加复杂度,可能超时或死等
实际生产最常用:关键链路强制读主 + 普通查询走从库。例如:注册后立即登录 → 读主库;发布文章后作者自己刷页面 → 读主库;其他用户浏览 → 读从库。

三、同步出现延迟后如何处理?(补偿与兜底)
既然延迟无法 100% 消除,必须有应对方案:

  1. 监控与告警
    持续监控 Seconds_Behind_Master(注意它超过 MAX_ALLOWED_PACKET 会重置为 0,不够准确)。

更可靠:监控 Master_Log_File 和 Read_Master_Log_Pos vs Relay_Master_Log_File 和 Exec_Master_Log_Pos,计算位点差距。

设置阈值(如延迟 > 5秒)触发告警,自动切换读写策略。

  1. 业务容忍设计
    多数场景(评论、点赞、非实时排行榜)允许短暂不一致,用户刷新后自然可见。

前端可做“乐观展示”:用户提交动作后,前端先本地更新 UI,后台异步确认。即使从库暂时没数据,用户感受不到。

  1. 延迟补偿机制
    读取降级:检测到延迟超过阈值时,将该请求临时切到主库(需要负载均衡器或数据库中间件支持)。

缓存兜底:写操作后更新 Redis(设置较短 TTL),读请求优先查缓存,缓存未命中再查从库。

异步修复:定时任务扫描主从差异表,修复不一致数据。

  1. 从库追赶加速
    多线程并行复制(MySQL 5.7+ 的 slave_parallel_workers,8.0 默认 logical_clock 模式),大幅提升重放速度。

提升从库硬件(SSD、更多 CPU)。

避免从库执行复杂 ANALYZE、大查询(可临时关闭从库查询服务,专心同步)。

拆解大事务:DELETE ... LIMIT 1000 循环提交。

  1. 最终一致性的兜底预案
    如果延迟长期无法解决,主动进行主从切换:将原从库提升为主库,并修复数据。配合 pt-table-checksum + pt-table-sync 工具修复不一致。

ES实际需求设计展示

作者: 时间: 2026-05-08 评论: 暂无评论

APP搜索设计案例demo

use Elasticsearch\ClientBuilder;

public static function singleton()
{
    if (empty(self::$client)) {
        $hosts        = self::getHost();
        $client       = ClientBuilder::create()->setHosts($hosts)->build();
        self::$client = $client;
    }
    return self::$client;
}

[数据同步核心代码]

public static function addAppV2($appInfo)
    {
        $isIos   = intval(stripos($appInfo['platform'], 'IOS') !== false);
        $isAz    = intval(stripos($appInfo['platform'], '安卓') !== false);
        $isH5    = intval(stripos($appInfo['platform'], 'H5') !== false);
        $isYgj   = intval(stripos($appInfo['platform'], 'YGJ') !== false);
        $isYyx   = intval(stripos($appInfo['platform'], 'PCYYX') !== false);
        $isAzH5  = intval($isAz || $isH5);
        $isIosH5 = intval($isIos || $isH5);

        $param = [
            'index' => self::APP_INDEX_V2,
            'id'    => $appInfo['id'],
            'body'  => [
                'id'              => $appInfo['id'],
                'state'           => $appInfo['state'],
                'is_ios'          => $isIos,
                'is_az'           => $isAz,
                'is_ios_h5'       => $isIosH5,
                'is_az_h5'        => $isAzH5,
                'is_ygj'          => $isYgj,
                'is_h5'           => $isH5,
                'is_pc_yyx'       => $isYyx,
                'classid'         => $appInfo['classid'],
                'app_id'          => $appInfo['app_id'],
                'is_az_h5_pc_yyx' => intval($isYyx || $isAzH5),
                'game_name'       => $appInfo['main_title'],
                'subtitle'        => $appInfo['subtitle'] ?? '',
                'title'           => $appInfo['new_title'],
                'mix_type'        => $appInfo['mix_type'] ?? 100,
            ]
        ];

        $addIndex = self::singleton()->index($param);
        return $addIndex;
    }

[搜索核心代码]
同步游戏数据到es数据库,通过function_score 设置权重

游戏名中含有 关键字 完全匹配权重设置10000
搜索词包含在标题中,且比例 ≥ 60% → 高权重
标题包含在搜索词中,且比例 ≤ 200% → 高权重

下载加权 5
日活加权 15
支付加权80

private function searchGameIdsV21()
    {
        $keyword = $this->keyword;

        $must = $mustNot = $scoreFun = [];

        $should[] = [
            'match' => [
                'game_name.keyword' => [
                    'query'     => $keyword,
                    'fuzziness' => floor(mb_strlen($keyword) / 4), // 表示容错字符
                    'boost'     => 1
                ]
            ]
        ];
        $should[] = [
            'match' => [
                'title.keyword' => [
                    'query'     => $keyword,
                    'fuzziness' => floor(mb_strlen($keyword) / 3),
                    'boost'     => 1
                ]
            ]
        ];
        $should[] = [
            'match' => [
                'cates.keyword' => [
                    'query'     => $keyword,
                    'fuzziness' => 1,
                    'boost'     => 1
                ]
            ]
        ];
        $should[] = [
            'multi_match' => [
                'query'  => $keyword,
                'fields' => [
                    'game_name', 'subtitle'
                ],
                'boost'  => 1,
            ]
        ];

        // 增加包含全量游戏名的权重
        $scoreFun[] = [
            'filter' => [
                'term' => [
                    'game_name.keyword' => $keyword,
                ]
            ],
            'weight' => 10000
        ];
        $scoreFun[] = [
            'filter' => [
                'term' => [
                    'title.keyword' => $keyword,
                ]
            ],
            'weight' => 10000
        ];
        $scoreFun[] = [
            'filter' => [
                'script' => [
                    'script' => [
                        'source' => "String title = doc['title.keyword'].value;title.contains(params.query) && (params.query.length() / (double) Math.round(doc['title_length'].value)) >= 0.6 || params.query.contains(title) && (params.query.length() / (double) Math.round(doc['title_length'].value)) <= 2",
                        'params' => [
                            'query' => $keyword
                        ]
                    ]
                ]
            ],
            'weight' => 10000
        ];
        $scoreFun[] = [
            'filter' => [
                'script' => [
                    'script' => [
                        'source' => "String title = doc['game_name.keyword'].value; title.contains(params.query) &&  (params.query.length() / (double) Math.round(doc['name_length'].value)) >= 0.6 ||  params.query.contains(title) && (params.query.length() / (double) Math.round(doc['name_length'].value)) <= 4",
                        'params' => [
                            'query' => $keyword
                        ]
                    ]
                ]
            ],
            'weight' => 10000
        ];

        // 近1日的累计实付*80%+昨日日活*15%+下载量*5%
        $scoreFun[] = [
            'script_score' => [
                'script' => [
                    'source' => "1 + Math.log1p(doc['true_down'].value)"
                ]
            ],
            'weight'       => 5,
        ];
        $scoreFun[] = [
            'script_score' => [
                'script' => [
                    'source' => "1 + Math.log1p(doc['yesterday_hy'].value)"
                ]
            ],
            'weight'       => 15,
        ];
        $scoreFun[] = [
            'script_score' => [
                'script' => [
                    'source' => "1 + Math.log1p(Math.ceil(doc['real_pay'].value))"
                ]
            ],
            'weight'       => 80,
        ];

        if (EcloudByService::isZkyCps() || AFrom::isADevice()) {
            $filter[] = [
                'match' => [
                    'is_az_h5_pc_yyx' => 1
                ]
            ];
        } else {
            $filter[] = [
                'match' => [
                    'is_ios_h5' => 1
                ]
            ];
            // iOS过滤模拟器游戏
            $mustNot[] = [
                'term' => [
                    'classid' => APP_CLASS_SIMULATOR,
                ]
            ];
        }
        $mustNot[] = [
            'term' => [
                'is_pc_yyx' => 1,
            ]
        ];

       
        // 只展示预约、运营中
        $mustNot[] = [
            'terms' => [
                'state' => [
                    XYApp::STATE_CLOSED,
                    XYApp::STATE_DISABLED,
                    XYApp::STATE_CLOSING,
                    XYApp::STATE_HX1,
                    XYApp::STATE_HX2,
                ]
            ]
        ];
        $param = [
            'index' => ElasticSearch::APP_INDEX_V3,
            'body'  => [
                'query' => [
                    'function_score' => [
                        'query'      => [
                            'bool' => []
                        ],
                        'functions'  => $scoreFun,
                        "score_mode" => "sum",
                        "boost_mode" => "sum"
                    ],
                ],

                'from' => ($this->page - 1) * $this->listRows,
                'size' => $this->listRows,
                'sort' => [
                    [
                        '_score' => ['order' => 'desc']
                    ]
                ],
            ],
        ];
        if ($must) {
            $param['body']['query']['function_score']['query']['bool']['must'] = $must;
        }
        if ($mustNot) {
            $param['body']['query']['function_score']['query']['bool']['must_not'] = $mustNot;
        }
        if ($filter) {
            $param['body']['query']['function_score']['query']['bool']['filter'] = $filter;
        }
        $param['body']['query']['function_score']['query']['bool']['should']               = $should;
        $param['body']['query']['function_score']['query']['bool']['minimum_should_match'] = 1;

        $esData   =self::singleton()->search($param);

记录几个特殊排序的例子

作者: 时间: 2026-05-07 评论: 暂无评论

在 MySQL 中按照 status 字段的特定顺序 1, 2, 0 排序(审核通过 → 驳回 → 待审核)。
在 MySQL 中有几种方式实现自定义排序:

  1. order by FIELD(status, 1, 2, 0)
  2. order by CASE status WHEN 1 THEN 1 WHEN 2 THEN 2 WHEN 0 THEN 3 END