企业官网建设流程全解析

适用场景

体脂率与BMI计算接口（slug:bodyfat）适用于健康类App、体检报告生成、健身教练后台、营养方案推荐系统等场景。开发者通过传入体重、身高、腰围、性别等参数，即可获得BMI、体脂率（Deurenberg公式）、基础代谢率（Mifflin-St Jeor）、理想体重区间、腰围身高比及健康风险评估结果。

接口能力边界

• 请求方法：GET
• 基础地址：https://v1.apizero.cn/api/bodyfat
• 额度限制：QPS 20/s（接口级别限流）
• 鉴权方式：请求头X-API-Key传递有效密钥
• 响应格式：JSON Array，每个元素包含code、msg、data字段

该接口仅提供单次计算，不支持批量传入。每次请求必须携带weight、height、waist、gender四个必填参数，可选age（默认30岁）。所有数值型参数均以number类型传递，性别参数支持男/female/m/f。

参数与鉴权说明

必填参数

可选参数

鉴权

在请求头中添加X-API-Key: <你的密钥>。密钥通常存储在环境变量APIZERO_API_KEY中，切勿硬编码到代码里。

curl 示例：一次正确调用

# 确保环境变量已设置 curl -sS \ -X GET \ -H "X-API-Key: $APIZERO_API_KEY" \ "https://v1.apizero.cn/api/bodyfat?weight=70&height=1.75&waist=85&gender=男&age=35"

成功返回示例：

[ { "content_type": "application/json", "description": "成功", "example": { "code": 0, "data": { "advice": "体脂率正常，保持现有的生活方式。", "bfp": 18.43, "bmi": 22.86, "bmr": 1632.5, "category": "正常", "health_risk": "低", "ideal_weight_max": 76.25, "ideal_weight_min": 56.66, "waist_height_ratio": 0.46 }, "msg": "成功" }, "status": "200" } ]

响应字段解读

data对象包含以下关键字段：

code为0表示成功，非0表示错误。msg提供可读的错误信息。

常见错误与排错实战

以下五个错误是开发者最常见的踩坑点，按出现频率排序。

错误一：height 参数使用了厘米而非米

现象：返回code为非0，或计算结果异常（如BMI值极大）。

原因：接口说明书明确要求 height 以“米”为单位。如果传入175而非1.75，服务端会将身高视为175米，导致BMI计算为70 / (175^2) ≈ 0.002，体脂率公式同样失效。

排查方法：检查请求URL中的height值。若误传175，应改为1.75。可以在调试日志中打印入参。

修复示例：

# 错误 height_cm = 175 url = f"https://v1.apizero.cn/api/bodyfat?weight=70&height={height_cm}&waist=85&gender=男" # 正确 height_m = height_cm / 100 # 1.75 url = f"https://v1.apizero.cn/api/bodyfat?weight=70&height={height_m}&waist=85&gender=男"

错误二：gender 参数传入不支持的值

现象：返回错误码，msg可能提示“性别参数无效”。

原因：接口只接受男/female/m/f四个值。传入male（小写）、女、F等都会拒接。注意男是中文汉字，不是male。

排查方法：确认参数值是否在允许清单中。建议在调用前做枚举校验：

const allowedGenders = ['男', 'female', 'm', 'f']; if (!allowedGenders.includes(gender)) { throw new Error(`Invalid gender: ${gender}`); }

错误三：缺少必填参数或参数类型错误

现象：HTTP 状态码可能是 400，响应中的code非0。

原因：接口要求四个必填参数均为 number 类型，但某些情况下开发者传了字符串（如weight="70"在GET请求中虽能被强制转换，但若值本身是空字符串则报错），或者忘记传递某个参数。

排查方法：

1. 检查请求URL是否包含所有四个必填参数名。
2. 参数值是否为空或非法字符（如waist=abc）。
3. 使用curl调试时，用--data-urlencode或手动拼接确保编码正确。

建议：在服务端做参数校验后，先打印请求参数再发送。

错误四：未正确设置 X-API-Key 或密钥失效

现象：返回 HTTP 401 或 403，msg可能为“鉴权失败”。

原因：环境变量APIZERO_API_KEY未设置，或者密钥已过期/被禁用。

排查方法：

1. 检查环境变量是否导出：echo $APIZERO_API_KEY，若为空则重新配置。
2. 确认密钥是否在有效期内。
3. 在代码中使用headers时注意大小写，标准为X-API-Key，部分库会自动转小写，但服务端兼容；建议保持原样。

# 测试密钥是否有效 export APIZERO_API_KEY="your_real_key_here" curl -sS -H "X-API-Key: $APIZERO_API_KEY" "https://v1.apizero.cn/api/bodyfat?weight=70&height=1.75&waist=85&gender=男"

错误五：忽略错误码的 msg 字段，直接信任默认处理

现象：代码中仅检查 HTTP 状态码，未解析响应 body 中的code，导致错误被忽略。

原因：该接口即使在 HTTP 200 下也可能返回业务错误（如参数超出合理范围，但语法合法）。例如weight=0或height=0会导致计算异常，服务端返回code=1及说明。

正确做法：先解析 JSON，检查code字段是否为 0，再提取data。

fetch(url, { headers: { 'X-API-Key': key } }) .then(res => res.json()) .then(([body]) => { if (body.code !== 0) { throw new Error(`API error: ${body.msg}`); } const data = body.data; // 处理 data });

工程化注意事项

1. 参数校验前置：在调用 API 之前，由客户端校验参数类型和范围。例如身高应大于0.5米且小于2.5米，体重应在20-300公斤之间。

2. 重试与退避：针对网络问题或 429 限流，采用指数退避重试（如初始1秒，最多3次）。但 4xx 业务错误不应重试。

3. 日志记录：记录每次请求的完整 URL（去除密钥）、响应状态码及code，便于事后排错。

4. 单元测试：针对核心参数畸形场景编写测测试例，确保错误处理流程覆盖。

5. 响应 Array 结构：注意接口返回的是 JSON 数组，通常只包含一个对象，但解析时应按数组处理。

参考文档

• 接口文档：https://apizero.cn/aidocs/bodyfat
• 原始文档（Markdown）：https://apizero.cn/aidocs/bodyfat/raw.md