必须编码的字符是除A-Z、a-z、0-9、-、.、_、~外的所有字节，包括空格（%20）、保留字符（如/、?、#等在数据中出现时）、中文及emoji等UTF-8多字节字符，且需按字节逐个编码，不得二次编码。
哪些字符必须被编码才能符合RFC3986
RFC3986明确将URL中“不安全”或“保留”的字符划分为两类：需要百分比编码的unreserved字符（仅允许A-Z、a-z、0-9、-、.、_、~）和“保留字符”（如/、?、#、[、]等），后者在特定上下文中不能随意编码。实际做URL路径或查询参数编码时，**默认应只对非unreserved字符编码**，且/、?等在路径中是合法分隔符，不应被编码——除非你正在构造查询值（比如q=hello/world里的/）。
常见错误是把空格编码成+（这是application/x-www-form-urlencoded的规则，不是RFC3986）；RFC3986要求空格必须编码为%20。
-
unreserved字符：不编码（A-Za-z0-9-._~） - 空格 →
%20（不是+） - 中文、emoji、控制字符 → 按UTF-8字节逐个编码（如
好→ UTF-8为0xE5 0xA5 0xBD→%E5%A5%BD） -
/、?、#等：在路径/查询键名中保留原义，仅在查询值中需编码（例如file=path/to.txt中的/要编码）
用std::ostringstream + std::hex手动编码最可控
标准库没有内置RFC3986编码函数，但用std::ostringstream拼接+std::hex格式化字节足够轻量、无依赖、可精确控制。关键点是：先转UTF-8（std::string本身即UTF-8），再对每个字节判断是否属于unreserved集合。
示例核心逻辑：
立即学习“C++免费学习笔记（深入）”；
组合式C++代码评审方案，融合静态分析、AI推理、多轮迭代评审和C++专项检查，适用于PR审查、增量代码审查、全项目评审和代码质量评分，触发词包括review cpp、cpp代码评审、C++review、代码审查。
#include <sstream>
#include <iomanip>
#include <cctype>
<p>std::string url<em>encode(const std::string& s) {
static const std::string unreserved = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-.</em>~";
std::ostringstream ret;
for (unsigned char c : s) {
if (unreserved.find(c) != std::string::npos) {
ret << c;
} else {
ret << '%' << std::uppercase << std::hex << std::setw(2) << std::setfill('0') << (int)c;
}
}
return ret.str();
}</p>注意：std::setw(2)和std::setfill('0')确保单字节0x5输出为%05而非%5；std::uppercase让A-F大写（RFC3986推荐大写，虽不强制）。
- 输入必须是UTF-8编码的
std::string；若源是std::u16string或std::wstring，先用std::wstring_convert<std::codecvt_utf8<char16_t>>（C++11/14）或C++20的std::text_encoding转换 - 不要对整个URL字符串统一编码——只编码路径段或查询值，避免把
https://里的:、/也编码了 - 性能敏感场景可预分配
ret.str().reserve(s.size() * 3)（最坏情况每个字节变3字符）
std::isalnum等C标准库函数不能直接用
std::isalnum、std::isalpha等函数依赖当前C locale，对非ASCII字符（如中文、é、ñ）行为不可靠，甚至可能崩溃（传入char负值给unsigned char重载前未转换）。RFC3986的unreserved集合是固定ASCII字符集，必须硬编码比对。
- 错误写法：
if (std::isalnum(c)) ret << c;—— 在LC_CTYPE=zh_CN.UTF-8下可能返回false，导致中文被错误编码为%E4%BD%A0（虽然结果对，但逻辑错；更糟的是某些locale下std::isalnum(0xC3)未定义） - 正确做法：只查硬编码字符串
"A-Za-z0-9-._~"，或用unsigned char查std::array<bool></bool>查表（更快） - 别信IDE自动补全的
<locale>方案——RFC3986不按语言区域定义合法字符
第三方库如cpp-httplib或Boost.URL的取舍
如果项目已用cpp-httplib，它提供httplib::detail::encode_url（内部函数，非公开API），不建议直接调用；Boost.URL（C++23前需单独编译）有boost::urls::encode，支持指定encode_opts，能区分路径/查询上下文，但引入Boost带来构建复杂度。
- 纯C++11/14项目：手写上面的
url_encode函数，50行内搞定，无依赖 - 已用Boost且需处理多种编码上下文（如路径 vs 查询键 vs 查询值）：用
boost::urls::encode并传boost::urls::pct_encode_opts::no_space_to_plus - 别用
cpr或libcurl自带的curl_easy_escape——它默认用+代空格，且不支持UTF-8多字节（只处理Latin-1）
最易被忽略的是：编码后的字符串不能再被二次编码。比如url_encode(url_encode("a b"))会把%20变成%2520，这是典型双编码bug，常见于中间件层层转义。务必保证“一次编码，一次使用”。
