45 lines
2.4 KiB
Markdown
45 lines
2.4 KiB
Markdown
# 编码规范（字符编码）
|
||
|
||
> 本规则因一次事故而立：批量改包名时用了非 UTF-8 感知的脚本，把中文注释整成乱码（`鐗堟湰`=版本、`寰湇鍔`=微服务），且引入 BOM。以下为硬性约束。
|
||
|
||
## 不变式（违反即 Bug）
|
||
|
||
1. **所有源码/配置/文本文件一律 UTF-8 编码**：`.java` `.xml` `.yml` `.yaml` `.properties` `.sql` `.md` `.vue` `.ts` `.js` `.json` 等。
|
||
2. **禁止 BOM**：UTF-8 文件不得带 BOM（`EF BB BF`）。BOM 会让 XML/YAML 解析、shell 脚本、diff 出错。
|
||
3. **禁止 GBK / GB2312 / GB18030 / Latin1 落盘**：任何环节（编辑器、脚本、终端重定向）都不得以非 UTF-8 写文件。
|
||
4. **禁止用非 UTF-8 感知的工具批量改写文本**：如必须批量替换，工具必须显式按 UTF-8 读、UTF-8 写（Python 用 `io.open(p, encoding='utf-8')`；`sed`/`grep` 在 UTF-8 locale 下运行）。
|
||
5. **换行**：统一 LF（`\n`），`.gitattributes` 固化，避免 CRLF 混入触发整文件 diff。
|
||
|
||
## 构建/工程配置（必须存在）
|
||
|
||
- **Maven**：父 pom 设
|
||
```xml
|
||
<properties>
|
||
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
|
||
<project.reporting.outputEncoding>UTF-8</project.reporting.outputEncoding>
|
||
</properties>
|
||
```
|
||
- **`.editorconfig`**（后端仓库和前端仓库根目录各一个 `.editorconfig` 文件）：
|
||
```
|
||
root = true
|
||
[*]
|
||
charset = utf-8
|
||
end_of_line = lf
|
||
insert_final_newline = true
|
||
```
|
||
- **前端**：Vite/Node 默认 UTF-8，源文件保持 UTF-8 无 BOM 即可。
|
||
- **Windows 终端**：PowerShell 默认输出可能是 GBK；**不要用 `>`/`>>` 重定向把含中文的内容写进源文件**（会按当前代码页编码）。要写文件用 UTF-8 感知的程序，不要靠 shell 重定向。
|
||
|
||
## 处理已损坏文件（mojibake 还原）
|
||
|
||
经典双重编码（UTF-8 被当 GBK 再存 UTF-8）可逆转：`坏文本.encode('gbk').decode('utf-8')`。
|
||
但若 mojibake 中已出现 `?`（0x3F），该字节已丢失、不可逆，只能按上下文重写注释。
|
||
|
||
## 检查表（提交前）
|
||
|
||
- [ ] 新增/修改的文本文件是 UTF-8 无 BOM（`file *.xml` 或编辑器状态栏确认）
|
||
- [ ] 没有出现 `鐗堟湰`/`寰湇`/`锛` 这类乱码片段
|
||
- [ ] 仓库根有 `.editorconfig`（charset=utf-8）
|
||
- [ ] 父 pom 有 `project.build.sourceEncoding=UTF-8`
|
||
- [ ] 批量文本替换用的是 UTF-8 感知工具，不是裸 `>` 重定向
|