hfb_sys/docs/charset-best-practices.md at 402c19320d462254aabfe4d3a74bb663e9f435a3

yml/hfb_sys

Fork 0

Files

T

yml 63d4011796 增加mysql默认编码

2026-06-05 21:27:26 +08:00

3.6 KiB

Raw Blame History

🔒 彻底杜绝字符编码问题的方案

本文档说明如何在整个技术栈中确保使用 UTF-8 编码，避免出现乱码问题。

1. MySQL 服务器配置（已完成 ✅）

配置文件： deploy/mysql/my.cnf

[client]
default-character-set = utf8mb4

[mysql]
default-character-set = utf8mb4

[mysqld]
character-set-server = utf8mb4
collation-server = utf8mb4_unicode_ci
init-connect = 'SET NAMES utf8mb4'
skip-character-set-client-handshake

Docker Compose 配置： deploy/docker-compose.prod.yml

mysql:
  command: --default-authentication-plugin=mysql_native_password --character-set-server=utf8mb4 --collation-server=utf8mb4_unicode_ci
  volumes:
    - ./mysql/my.cnf:/etc/mysql/conf.d/my.cnf:ro

2. 数据库连接字符集（已完成 ✅）

配置： backend/internal/config/config.go

MySQLDSN: "hfb:secret@tcp(127.0.0.1:3306)/hfb_sys?charset=utf8mb4&parseTime=True&loc=Local"

关键参数：

charset=utf8mb4 - 强制使用 UTF-8 编码
parseTime=True - 正确解析时间类型
loc=Local - 使用本地时区

3. 数据库表结构（已完成 ✅）

迁移文件： backend/migrations/*.sql

CREATE TABLE table_name (
  ...
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

转换现有表：

ALTER TABLE table_name CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

4. 后端 API 响应头（建议添加）

在 HTTP 响应中设置：

w.Header().Set("Content-Type", "application/json; charset=utf-8")

5. 前端 HTML 元信息（已完成 ✅）

index.html：

<meta charset="UTF-8">

6. 文件编辑器配置

确保所有代码文件使用 UTF-8：

.editorconfig - 统一团队编码
IDE 设置 - 文件编码为 UTF-8
Git 设置 - 避免行尾符问题

7. 验证检查清单

部署后执行以下命令验证：

# 1. 检查 MySQL 字符集配置
docker exec -i deploy-mysql-1 mysql -u hfb -p<password> -e "SHOW VARIABLES LIKE 'character%';"

# 2. 检查表字符集
docker exec -i deploy-mysql-1 mysql -u hfb -p<password> hfb_sys -e "SHOW CREATE TABLE announcements\G"

# 3. 验证数据正确性
docker exec -i deploy-mysql-1 mysql -u hfb -p<password> hfb_sys -e "SELECT id, title FROM announcements LIMIT 3;"

8. 常见问题排查

问题：数据库中已有乱码数据

# 执行修复脚本
docker exec -i deploy-mysql-1 mysql -u hfb -p<password> hfb_sys < backend/migrations/000008_fix_announcement_charset.sql

问题：新插入的数据仍然乱码

检查数据库连接 DSN 是否包含 charset=utf8mb4
检查 MySQL 配置文件是否生效
重启 MySQL 容器使配置生效

问题：只有某些字段乱码

-- 转换特定列
ALTER TABLE table_name MODIFY column_name VARCHAR(255) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

9. 部署流程

每次部署时确保：

✅ MySQL 配置文件已挂载
✅ 环境变量 MYSQL_DSN 包含 charset 参数
✅ 新建表使用正确的字符集
✅ 迁移脚本指定字符集

10. 开发规范

新建表时必须指定：

CREATE TABLE new_table (
  ...
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='表注释';

修改表时保持一致：

ALTER TABLE existing_table CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

总结

通过以上配置，确保了从数据库服务器 → 连接驱动 → 表结构 → 应用层 → 前端展示的完整链路都使用 UTF-8 编码，彻底杜绝乱码问题。

3.6 KiB Raw Blame History Unescape Escape