数据格式

概述

环能聚合API采用JSON（JavaScript Object Notation）作为标准数据交换格式，确保数据结构清晰、易于阅读和跨平台兼容。

基本规范

数据格式： JSON (RFC 8259)

编码： UTF-8 (无BOM)

媒体类型： application/json

字符转义： RFC 8259标准

JSON结构规范

基础数据类型

类型	示例	描述	限制
string	`"hello world"`	字符串	最大长度65535字符
number	`42` 或 `3.14`	数值	64位双精度浮点数
boolean	`true` 或 `false`	布尔值	仅true/false
null	`null`	空值	-
array	`[1, 2, 3]`	数组	最大元素1000个
object	`{"key": "value"}`	对象	最大属性100个

标准响应格式

成功响应

{
    "code": 0,
    "message": "success",
    "data": {
        // 具体业务数据
    },
    "timestamp": 1640995200000,
    "request_id": "req_123456789"
}

错误响应

{
    "code": 400,
    "message": "参数错误",
    "error": {
        "type": "validation_error",
        "details": [
            {
                "field": "mobile",
                "message": "手机号格式不正确"
            }
        ]
    },
    "timestamp": 1640995200000,
    "request_id": "req_123456789"
}

时间戳格式

格式类型	示例	精度	时区
Unix时间戳	`1640995200000`	毫秒	UTC
ISO 8601	`2022-01-01T00:00:00Z`	秒	UTC
ISO 8601带毫秒	`2022-01-01T00:00:00.123Z`	毫秒	UTC

数据验证规则

字符串验证

验证类型	规则	示例	错误消息
手机号	^1[3-9]\d{9}$	`"13800138000"`	手机号格式不正确
邮箱	标准邮箱格式	`"user@example.com"`	邮箱格式不正确
身份证号	15或18位	`"110101199001011234"`	身份证号格式不正确
URL	标准URL格式	`"https://example.com"`	URL格式不正确

数值验证

验证类型	范围	示例	说明
整数	-2^31 到 2^31-1	`42`	32位有符号整数
长整数	-2^63 到 2^63-1	`9223372036854775807`	64位有符号整数
浮点数	IEEE 754双精度	`3.1415926`	15-17位有效数字
金额	精确到分	`99.99`	最多2位小数

嵌套结构示例

复杂对象结构

用户信息对象

{
    "user": {
        "id": 12345,
        "name": "张三",
        "mobile": "13800138000",
        "email": "zhangsan@example.com",
        "profile": {
            "avatar": "https://example.com/avatar.jpg",
            "birthday": "1990-01-01",
            "gender": "male",
            "location": {
                "province": "北京市",
                "city": "北京市",
                "district": "朝阳区"
            }
        },
        "settings": {
            "notification": true,
            "language": "zh-CN",
            "timezone": "Asia/Shanghai"
        },
        "created_at": 1640995200000,
        "updated_at": 1640995200000
    }
}

数组结构示例

订单列表

{
    "orders": [
        {
            "order_id": "ORD20240001",
            "user_id": 12345,
            "items": [
                {
                    "product_id": "PROD001",
                    "name": "商品A",
                    "price": 99.99,
                    "quantity": 2,
                    "specifications": {
                        "color": "红色",
                        "size": "XL"
                    }
                }
            ],
            "total_amount": 199.98,
            "status": "paid",
            "created_at": 1640995200000
        }
    ],
    "pagination": {
        "page": 1,
        "per_page": 20,
        "total": 100,
        "total_pages": 5
    }
}

数据压缩

压缩选项

压缩算法	压缩率	CPU消耗	适用场景
无压缩	0%	最低	小数据量、调试模式
gzip	60-80%	中等	标准API响应
brotli	70-90%	较高	大文本数据、静态资源

最佳实践

✅ 推荐做法

使用一致的字段命名规范（snake_case）
提供清晰的错误信息和错误码
使用标准的时间戳格式
限制嵌套层级不超过5层
数组元素数量控制在合理范围内
使用null表示缺失值而非空字符串
为每个响应提供唯一的request_id

⚠️ 避免做法

避免使用过长的字段名
避免在JSON中嵌入HTML
避免使用不明确的缩写
避免混用不同的命名风格
避免在数值中使用字符串表示