字符编码工程：UTF-8 自同步设计、Unicode 正规化形式与编码安全

引导字节：  0xxxxxxx, 110xxxxx, 1110xxxx, 11110xxx
后续字节：  10xxxxxx

如果落在 10xxxxxx 字节上，向前跳过直到碰到
不以 10 开头的字节。那就是下一个字符的起始。

码位：0x4E2D = 0100 1110 0010 1101（16 位）
范围：U+0800–U+FFFF → 3 字节形式：1110xxxx 10xxxxxx 10xxxxxx

将 16 位分配到槽位：
  1110[0100] 10[111000] 10[101101]
       ^^^^     ^^^^^^     ^^^^^^
  字节 1: 0xE4    字节 2: 0xB8    字节 3: 0xAD

验证：在 UTF-8 文件中 grep "中" 就是搜索字节 E4 B8 AD。
这些字节（0xE4, 0xB8, 0xAD）都不在 0x00–0x7F 范围内，
所以不会与 ASCII 字符混淆。

# 这两个看起来一样但字节序列不同：
a = "é"   # U+00E9（预组合：带锐音的拉丁小写 e）
b = "é"   # U+0065 U+0301（分解：e + 组合锐音符）

a == b     # False！
len(a)     # 1
len(b)     # 2

é (U+00E9) ↔ e + ◌́ (U+0065 U+0301)   [规范等价]

fi (U+FB01) → fi (U+0066 U+0069)   [兼容：连字 → 字母]
① (U+2460) → 1 (U+0031)           [兼容：带圈 → 普通]
Ⅳ (U+2163) → IV                   [兼容：罗马数字]

import unicodedata

text = "Caf\u0065\u0301"  # "Café"，分解形式的 é

nfc = unicodedata.normalize('NFC', text)
nfd = unicodedata.normalize('NFD', text)

print(len(text))  # 5（C, a, f, e, 组合重音）
print(len(nfc))   # 4（C, a, f, é）
print(len(nfd))   # 5（始终完全分解）

# 数据库键比较必须先正规化
assert unicodedata.normalize('NFC', user_input) == stored_value

import os
import unicodedata

filename = "café.txt"
os.path.exists(filename)  # 在 macOS 上如果文件名是 NFC 可能失败

# 安全的跨平台比较
def safe_filename_compare(a, b):
    return unicodedata.normalize('NFC', a) == unicodedata.normalize('NFC', b)

U+002F 用 1 字节: 2F              （合法）
U+002F 用 2 字节: C0 AF          （非法超长）
U+002F 用 3 字节: E0 80 AF       （非法超长）

显示："document[RLO]fdp.exe"
看起来像："documentexe.pdf"

用户输入: "malicious.php\x00.jpg"
PHP 检查: endsWith(".jpg") → 通过
C fopen(): 看到 "malicious.php"（在 \x00 处停止）

# "中文"的 UTF-8 字节用 Latin-1 解码
"中文".encode('utf-8')        # b'\xe4\xb8\xad\xe6\x96\x87'
b'\xe4\xb8\xad\xe6\x96\x87'.decode('latin-1')  # '中æ\x96\x87'（乱码）

# "中文"的 GBK 字节用 UTF-8 解码
"中文".encode('gbk')          # b'\xd6\xd0\xce\xc4'
b'\xd6\xd0\xce\xc4'.decode('utf-8', errors='replace')  # '��ζ'（乱码）

-- 失败：emoji 存入 utf8 列
INSERT INTO messages (text) VALUES ('Hello 😀');
-- Error: Incorrect string value '\xF0\x9F\x98\x80' for column 'text'

-- 😀 emoji 是 U+1F600，需要 4 个 UTF-8 字节（F0 9F 98 80）

-- 正确：使用 utf8mb4 以支持完整 Unicode
ALTER TABLE messages CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

-- 新表
CREATE TABLE messages (
    id INT PRIMARY KEY,
    text VARCHAR(255) CHARACTER SET utf8mb4
) DEFAULT CHARSET=utf8mb4;

-- 连接字符集
SET NAMES utf8mb4;

# str：Unicode 码位序列（抽象文本）
text = "Hello 中文"
type(text)       # <class 'str'>
len(text)        # 8（码位数，不是字节数）

# bytes：原始字节序列（编码后数据）
encoded = text.encode('utf-8')
type(encoded)    # <class 'bytes'>
len(encoded)     # 12（H,e,l,l,o,空格 = 6 字节 + 中 = 3 + 文 = 3）

# 不能混合 str 和 bytes
text + encoded   # TypeError

     str（文本）             bytes（网络/磁盘）
  ┌─────────────┐         ┌─────────────────┐
  │ Unicode 码位 │ encode  │ 原始字节流       │
  │              │────────→│（UTF-8、GBK、…）│
  │              │←────────│                  │
  │              │ decode  │                  │
  └─────────────┘         └─────────────────┘
                  ↑
           编码边界：
           所有 I/O 跨越此处

# 读文件
with open('data.txt', encoding='utf-8') as f:
    text = f.read()  # 返回 str（已解码）

# 网络响应
response = urllib.request.urlopen(url)
raw = response.read()            # bytes
text = raw.decode('utf-8')       # str

# 写输出
with open('output.txt', 'w', encoding='utf-8') as f:
    f.write(text)  # str → bytes 隐式发生

import os

# Unix 文件名是字节，不保证是 UTF-8
# Python 用 'surrogateescape' 错误处理器解码它们
entries = os.listdir('.')  # 返回 str，但可能包含代理

# 一个包含非法 UTF-8 字节 0xFF 的文件名：
# Python 将其表示为 U+DCFF（代理码位）
# 这样可以正确往返转换回原始字节

// TextDecoder 遵循 WHATWG 编码标准
const decoder = new TextDecoder('windows-1252');
const text = decoder.decode(bytes);

// 'fatal' 模式在遇到非法序列时抛出错误而非替换
const strictDecoder = new TextDecoder('utf-8', { fatal: true });
try {
  strictDecoder.decode(invalidBytes);
} catch (e) {
  // TypeError: invalid UTF-8 sequence
}

"café".length            // 4 或 5（取决于正规化）
"👨‍👩‍👧‍👦".length      // 11（7 个码位作为 UTF-16 单元）
"🇯🇵".length            // 4（2 个区域指示符号，各为代理对）
"நி".length              // 2（泰米尔语 NI = 辅音 + 元音符号）

// 用户感知的：
// "café"    = 4 个字符
// "👨‍👩‍👧‍👦" = 1 个字符（家庭 emoji）
// "🇯🇵"    = 1 个字符（国旗）
// "நி"      = 1 个字符（音节）

function graphemeLength(str) {
  const segmenter = new Intl.Segmenter('en', { granularity: 'grapheme' });
  return [...segmenter.segment(str)].length;
}

graphemeLength("👨‍👩‍👧‍👦")  // 1
graphemeLength("café")         // 4
graphemeLength("🇯🇵")         // 1

# chardet / charset-normalizer 方法：
# 1. 检查 BOM（如果存在则确定）
# 2. 尝试 UTF-8 严格解码 —— 如果有效，几乎确定是 UTF-8
# 3. 检查编码特有的字节模式：
#    - Shift_JIS：0x81-0x9F 或 0xE0-0xEF 为引导字节
#    - GBK：0x81-0xFE 为引导字节，0x40-0xFE 为尾随
#    - EUC-KR：0xA1-0xFE 为引导和尾随
# 4. 字符频率分析（语言模型）

import charset_normalizer

results = charset_normalizer.from_bytes(raw_bytes)
best = results.best()
print(best.encoding)    # 如 'utf-8', 'gbk', 'shift_jis'
print(best.language)    # 如 'Chinese', 'Japanese'