SQLx 默认将数据库文本字段作为 []byte（即 []uint8）返回，而 json.Marshal 会自动将其序列化为 Base64 字符串；正确做法是使用带结构体标签的 StructScan 替代 MapScan，让字段类型明确为 string，从而获得可读的 JSON 输出。
sqlx 默认将数据库文本字段作为 `[]byte`（即 `[]uint8`）返回，而 `json.marshal` 会自动将其序列化为 base64 字符串；正确做法是使用带结构体标签的 `structscan` 替代 `mapscan`，让字段类型明确为 `string`，从而获得可读的 json 输出。
在使用 sqlx 进行数据库查询时，若观察到 JSON 响应中本该是普通字符串的字段（如 cityName、countryName）却显示为类似 "VHJvbg==" 的 Base64 编码形式，这并非数据损坏或编码错误，而是 Go 标准库与 sqlx 行为协同作用下的预期表现——根源在于底层 SQL 驱动（如 pq 或 mysql）对文本列的默认扫描目标类型。
? 问题本质：[]byte vs string
Go 的 database/sql 接口要求 Scan 方法接收具体类型的指针。当使用 rows.MapScan(row) 时，sqlx 会将每一列值按驱动原生格式填充进 map[string]interface{}。对于 PostgreSQL、MySQL 等多数驱动，TEXT/VARCHAR 类型默认以 []uint8（等价于 []byte）形式返回，而非 string。而 json.Marshal 在遇到 []byte 时，严格遵循 JSON 规范，将其编码为 Base64 字符串（RFC 4648），因此你看到的是合法但非预期的输出。
从 spew.Dump 输出可清晰验证这一点：
"cityName": ([]uint8) (len=9 cap=9) {
00000000 54 72 6f 6e 64 68 65 69 6d |Trondheim|
}
这说明 cityName 实际字节内容完全正确（T r o n d h e i m ASCII 编码），只是被误当作二进制数据序列化了。
✅ 正确解法：使用结构体 + StructScan
避免 MapScan 的类型模糊性，改用强类型的 StructScan，并配合 db 和 json 标签精确控制映射逻辑：
type City struct {
CityID int64 `db:"cityId" json:"cityId"`
CityName string `db:"cityName" json:"cityName"`
Admin1Name string `db:"admin1Name" json:"admin1Name"`
CountryName string `db:"countryName" json:"countryName"`
SearchString string `db:"searchString" json:"searchString"`
}
// 替换原代码中的 MapScan 循环：
results := []City{}
for rows.Next() {
var city City
if err := rows.StructScan(&city); err != nil {
return err
}
results = append(results, city)
}
b, err := json.Marshal(results)
if err != nil {
return err
}
w.Header().Set("Content-Type", "application/json")
w.Write(b)
✅ 优势：
- 字段类型明确为 string，json.Marshal 直接输出 UTF-8 字符串；
- db 标签精准匹配 SQL 列别名（区分大小写！）；
- json 标签控制 API 响应字段名，实现关注点分离。
⚠️ 关键注意事项
结构体字段名必须导出（首字母大写）
Go 的 json 和 sqlx 包均无法访问未导出字段（小写开头），否则扫描失败或忽略。db 标签值须与 SQL 列别名完全一致
例如你的查询中写了 city.geonameid AS cityId，则 db 标签必须为 "cityId"（注意大小写）。若写成 "cityid" 或 "CityId" 将导致 sql.ErrNoRows 或 missing destination name 错误。-
标签分隔符必须是空格，不可用 Tab 或逗号
如问题中所述，以下写法无效（会导致解析失败）：CityID int64 `db:"cityId",json:"cityId"` // ❌ 逗号分隔 CityID int64 `db:"cityId" json:"cityId"` // ❌ Tab 分隔
正确写法（仅空格）：
CityID int64 `db:"cityId" json:"cityId"` // ✅
-
NULL 安全：使用指针或 sql.NullString（推荐）
若数据库列允许 NULL，直接使用 string 可能 panic。更健壮的方式：Admin1Name *string `db:"admin1Name" json:"admin1Name,omitempty"` // 或 import "database/sql" Admin1Name sql.NullString `db:"admin1Name" json:"admin1Name,omitempty"`
? 补充：为什么 MapScan 不修复？
MapScan 的设计目标是动态、无模式地处理任意查询结果，牺牲类型安全换取灵活性。它不尝试“猜测”文本列应转为 string，因为：
- 某些场景下 []byte 确实是合理需求（如处理二进制 blob）；
- 自动转换可能引发编码歧义（如数据库实际存的是 Latin-1 字节流）；
- 保持与 database/sql 原生行为一致，降低学习成本。
因此，明确的结构体定义始终是生产环境的最佳实践——它同时提升可读性、可维护性与序列化正确性。
通过以上调整，你的 API 将返回干净、可读的 JSON：
[
{
"cityId": 1605268,
"cityName": "Tron",
"admin1Name": "Uttaradit",
"countryName": "Thailand",
"searchString": "Tron Tron Thailand"
}
]
这才是开发者与前端期望的真正字符串结果。
