yumoqing/apppublic

Fork 0

yumoqing 83ff81e5e0 bugfix

2025-10-05 11:23:33 +08:00

6.0 KiB

Raw Blame History

技术文档：JSON 编码与解码工具模块

本模块提供了一组用于处理 Python 数据结构的 JSON 序列化与反序列化工具函数，支持 Unicode 转换、统一编码处理以及标准化的响应格式封装。

功能概述

该模块主要实现以下功能：

统一字符串编码转换（uni_str）：将任意嵌套数据结构中的字符串递归转换为 Unicode 字符串（Python 2 环境下），确保编码一致性。
标准响应构造：提供 success() 和 error() 函数以返回统一格式的成功/错误响应对象。
安全的 JSON 序列化与反序列化：通过 jsonEncode 和 jsonDecode 实现对复杂数据类型的兼容性处理。

⚠️ 注意：此代码适用于 Python 2 环境（使用了 unicode 类型）。在 Python 3 中需进行相应调整。

函数说明

`uni_str(a, encoding)`

递归地将输入数据结构中所有字符串转换为指定编码的 Unicode 字符串。

参数

参数	类型	描述
`a`	任意类型	输入的数据对象（如 str、dict、list、bool 等）
`encoding`	str	字符串编码方式，默认通常为 `'utf-8'`

返回值

返回一个与输入结构相同但所有字符串均为 Unicode 类型的对象。

处理逻辑

输入类型	处理方式
`None`	返回 `None`
`list` 或 `tuple`	遍历每个元素并递归调用 `uni_str`，返回新列表或元组
`dict`	遍历键值对，分别对键和值递归处理，返回新字典
`bool`	直接返回原值（不转换）
`unicode`	已是 Unicode，直接返回
`str` 或具有 `__str__` 方法的对象	调用 `str()` 并使用指定编码解码为 `unicode`
其他类型（int、float 等）	直接返回原值

示例

uni_str("hello", "utf-8")  # 输出: u'hello'
uni_str({"name": "张三"}, "utf-8")  # 输出: {u'name': u'\u5f20\u4e09'}

`success(data)`

构造一个表示操作成功的标准响应对象。

参数

参数	类型	描述
`data`	任意可序列化对象	成功时返回的数据内容

返回值

{
  "success": true,
  "data": data
}

示例

success({"id": 1, "name": "Alice"})
# 输出: {'success': True, 'data': {'id': 1, 'name': 'Alice'}}

`error(errors)`

构造一个表示操作失败的标准错误响应对象。

参数

参数	类型	描述
`errors`	list/dict/str	错误信息，可以是字符串、列表或字典形式的错误描述

返回值

{
  "success": false,
  "errors": errors
}

示例

error("用户名不能为空")
# 输出: {'success': False, 'errors': '用户名不能为空'}

error(["字段A无效", "字段B缺失"])
# 输出: {'success': False, 'errors': ['字段A无效', '字段B缺失']}

`jsonEncode(data, encode='utf-8')`

将任意 Python 对象安全地编码为 JSON 字符串。

参数

参数	类型	描述
`data`	任意对象	待序列化的数据
`encode`	str	编码格式，默认为 `'utf-8'`

流程

使用 uni_str(data, encode) 将所有字符串转换为 Unicode。
使用 json.dumps() 将处理后的数据序列化为 JSON 字符串。

返回值

类型：str
内容：合法的 JSON 格式字符串

示例

jsonEncode({"msg": "你好世界"})  
# 输出: '{"msg": "\\u4f60\\u597d\\u4e16\\u754c"}'

`jsonDecode(jsonstring)`

将 JSON 字符串解析为 Python 对象。

参数

参数	类型	描述
`jsonstring`	str	合法的 JSON 字符串

返回值

解析后的 Python 对象（dict、list、str、int 等）

异常处理

若输入不是合法 JSON，会抛出 ValueError（由 json.loads 抛出）

示例

jsonDecode('{"name": "Bob", "age": 30}')
# 输出: {u'name': u'Bob', u'age': 30}

使用示例

# 构造成功响应并编码为 JSON
response = success({"user_id": 123, "username": "test_user"})
json_str = jsonEncode(response)
print(json_str)
# 输出: {"success": true, "data": {"user_id": 123, "username": "test_user"}}

# 解码 JSON 字符串
decoded = jsonDecode(json_str)
print(decoded['data']['username'])  # 输出: test_user

# 构造错误响应
err_resp = error(["密码太短", "邮箱格式错误"])
err_json = jsonEncode(err_resp)
print(err_json)
# 输出: {"success": false, "errors": ["密码太短", "邮箱格式错误"]}

注意事项

Python 版本兼容性
- 此代码基于 Python 2 设计（依赖 unicode 类型）。
- 在 Python 3 中，unicode 应替换为 str，str 替换为 bytes，建议重写以适配 Python 3 的字符串模型。
性能考虑
- uni_str 是递归函数，对于深度嵌套或大型数据结构可能影响性能。
- 建议仅在必要时使用，或考虑缓存机制优化。
安全性
- jsonDecode 不做额外校验，请确保输入来源可信，防止注入攻击。
编码假设
- 所有字符串预期使用 UTF-8 编码。若传入其他编码（如 GBK），需确保数据真实编码匹配。
对象方法调用风险
- 在 uni_str 中调用了 getattr(a, '__str__') 并执行 str(a)，应确保对象的 __str__ 方法无副作用。

版本信息

兼容环境：Python 2.x
依赖库：json（标准库）

✅ 推荐用于需要统一响应格式与编码处理的传统 Web API 后端项目（如 Django 1.x / Flask 配合 Python 2）。

6.0 KiB Raw Blame History Unescape Escape