FitExerciseDB API 响应字段详解

无论在列表中还是单独返回，每个动作都有相同的 16 个字段。5 个必填字段说明这个动作是什么、锻炼哪块肌肉，其余字段补充训练和热量信息。

bodyPart、target 和 equipment 的准确取值来自分类接口，详见 API 文档。

只有 id、name、bodyPart、target 和 equipment 有保证。请把其余 11 个字段建模为可选且可为空，再逐字段决定空值在你的界面上意味着什么。与 API 一致的 TypeScript 类型如下：

type Exercise = {
  id: string;                 // "0001", keep it a string
  name: string;
  bodyPart: string;
  target: string;
  equipment: string;
  category?: string | null;
  difficulty?: string | null;
  mechanic?: string | null;
  force?: string | null;
  met?: number | null;
  caloriesPerMinute?: number | null;
  averageCaloriesPerMinute?: number | null;
  averageCaloriesPerHour?: number | null;
  secondaryMuscles?: string[] | null;
  instructions?: string[] | null;
  language?: "en" | "fr" | "es" | "pt" | "zh" | "ja";
};

目前的数据中，全部 1324 个动作的 16 个字段都有值，但数据库结构允许为 null，所以不要依赖这一点。

两条规则能避免大多数 bug。第一，instructions 为 null 时隐藏步骤区块，而不是渲染一个空列表。第二，调用热量接口之前先检查 met：没有 MET 值的动作会返回 422 错误，而不是一个数字。

caloriesPerMinute 是按典型体重存储的数值，用于在列表中快速展示。averageCaloriesPerMinute 只是它的另一个更直观的名字，averageCaloriesPerHour 则是该数值乘以 60 后取整（每分钟 4.3 千卡对应每小时 258 千卡）。它们都不知道你的用户是谁。

若要个性化估算，请把用户体重和时长传给 GET /v1/exercises/{id}/calories?bodyweightKg=80&minutes=30，它会用该动作的 MET 乘以体重和时间。计算方法与注意事项见 MET 热量指南。MET 数值来自 Compendium of Physical Activities，因此任何结果都只是估算。

列表和搜索共用同一个外层：data 中是数组，pagination 对象包含 page、pageSize 和 total。默认每页 50 条，最大 100 条，所以按最大页容量取完 1,324 个动作需要 14 次请求。我们文档中的部分示例还显示了 totalPages 字段；请自行计算，这样代码在两种情况下都能运行：

{
  "data": [ { "id": "0001", "name": "3/4 Sit-up", "bodyPart": "Waist", "target": "Abs", "equipment": "Body Weight" } ],
  "pagination": { "page": 1, "pageSize": 50, "total": 1324 }
}

const pages = Math.ceil(total / pageSize); // 1324 / 100 = 14

单个动作接口 GET /v1/exercises/{id} 返回相同的 16 个字段，另外多一个 HAL 风格的 _links 对象。calories 链接是模板化的，客户端只需填入两个查询参数，无需手写 URL。列表不带 _links。

"_links": {
  "self": { "href": "/v1/exercises/0001" },
  "related": { "href": "/v1/exercises/0001/related" },
  "calories": { "href": "/v1/exercises/0001/calories{?bodyweightKg,minutes}", "templated": true },
  "marketplacePreview": { "href": "/marketplace/preview/0001.gif" }
}

加上 ?lang=fr（或 es、pt、zh、ja）会翻译 name、bodyPart、target、equipment、secondaryMuscles 和 instructions，并把 language 设为你请求的代码。它不会改动 id、数值字段，也不会改动 category、difficulty、mechanic 和 force 这四个标签，它们保持原样。因此数字只需缓存一次，各语言只需重新获取文本。

语言如何选定，以及为什么搜索词应保持英文，请见搜索与语言指南。想亲自试用，可以浏览动作数据库或阅读文档。 响应里没有图片字段：请看如何购买并嵌入 ExerciseDB GIF和运动 API 的 GIF 与视频支持。