📚 课程目录第4章 API基础概念

4. API基础概念：RESTful API设计原则、HTTP方法、状态码含义

在供应链计划系统中，需求预测模块通常以微服务或独立服务的形式部署，前端界面、数据中台、甚至其他业务系统（如采购、生产排程）都需要通过API（应用程序编程接口）与预测引擎交互。RESTful API是目前最主流的接口设计风格，理解其核心原则、HTTP方法及状态码是进行接口调试与数据传输的基石。

4.1 RESTful API设计原则

REST（Representational State Transfer，表现层状态转移）是一种架构风格，而非严格标准。在供应链预测场景中，遵循以下核心原则能保证接口的清晰、可维护与高扩展性：

资源导向（Resource-Oriented）： 将一切业务实体抽象为“资源”。例如：/forecasts（预测单）、/products（物料）、/demand-history（历史需求）。
无状态（Stateless）： 服务器端不保存客户端请求的上下文。每次请求必须包含所有必要信息（如认证令牌、参数），这极大提升了预测服务的水平扩展能力。
统一接口（Uniform Interface）： 使用标准的HTTP方法操作资源，并使用标准的状态码反馈结果。
可缓存（Cacheable）： 对于不频繁变动的预测基础数据（如物料主数据），应通过HTTP缓存机制减少重复计算与传输。
分层系统（Layered System）： 客户端无需知道直接与它通信的是预测引擎本身，还是中间的网关或负载均衡器。

供应链实践提示： 在设计预测API时，资源命名应使用名词复数形式。例如，使用 /api/v1/forecasts 而非 /api/v1/getForecast。版本号（v1）应放在URL中，以便未来升级预测算法时兼容旧版本。

4.2 HTTP方法（GET/POST/PUT/DELETE）

HTTP方法定义了客户端对资源执行的操作类型。在需求预测API中，每个方法都有明确的语义和用途。以下是四种最常用方法的对比：

HTTP方法	CRUD对应	幂等性	请求体（Body）	供应链预测典型场景
GET	读取（Read）	是	无	查询指定物料ID的预测结果：`GET /forecasts?productId=1001`
POST	创建（Create）	否	有	提交新的需求预测任务：`POST /forecasts/jobs`
PUT	更新/替换（Update）	是	有	全量更新某个预测单的配置参数：`PUT /forecasts/123`
DELETE	删除（Delete）	是	无	删除一个已失效的预测任务：`DELETE /forecasts/jobs/456`

    幂等性（Idempotency）关键点： 幂等意味着无论调用一次还是多次，资源的状态结果相同。例如，PUT /forecasts/123 无论执行几次，最终该预测单的数据都是请求体指定的内容。而 POST 每次调用都会创建一个新资源（如新的预测任务ID），因此不幂等。在调试重试机制时，必须区分这一点。

4.3 HTTP状态码含义

状态码是服务器对请求处理结果的标准化反馈。在调试预测接口时，通过状态码可以快速定位问题。状态码分为五大类，以下是供应链场景中最常见的状态码：

2xx 成功类：
- 200 OK： 请求成功。常用于 GET 返回预测数据，或 PUT 更新成功。
- 201 Created： 资源创建成功。常用于 POST 提交预测任务后，返回新任务的ID。
- 204 No Content： 删除成功或操作成功但无返回体。常用于 DELETE 操作。
3xx 重定向类：
- 301/302： 资源URL已变更。在API版本升级或服务迁移时可能出现。
- 304 Not Modified： 资源未修改，可使用缓存。用于预测基础数据的缓存验证。
4xx 客户端错误类：
- 400 Bad Request： 请求参数错误（如日期格式错误、缺少必填字段）。
- 401 Unauthorized： 未提供或提供了无效的认证令牌。
- 403 Forbidden： 已认证但无权限访问该预测资源。
- 404 Not Found： 请求的资源（如指定的预测单ID）不存在。
- 422 Unprocessable Entity： 请求体语法正确，但语义错误（如预测时间范围超过系统限制）。
- 429 Too Many Requests： 请求频率超过限流阈值，常见于高并发预测调用场景。
5xx 服务器错误类：
- 500 Internal Server Error： 预测引擎内部发生未捕获异常。
- 502 Bad Gateway： 网关或代理无法从上游预测服务获取有效响应。
- 503 Service Unavailable： 预测服务暂时过载或正在维护。
- 504 Gateway Timeout： 预测计算超时，常见于复杂模型运算耗时过长。

调试避坑指南： 不要将 404 与 400 混淆。404表示资源不存在（URL路径错误或ID无效），而400表示请求格式有问题。在预测接口调试中，如果收到 500 错误，应优先检查预测引擎的日志，而非盲目修改客户端代码。

4.4 接口调试示例：使用cURL调用预测API

以下是一个使用cURL工具调试需求预测API的完整示例，涵盖了GET和POST方法：

# 1. 查询物料ID为1001的预测结果（GET请求）
curl -X GET "https://api.supplychain.com/v1/forecasts?productId=1001" \
     -H "Authorization: Bearer <your_>" \
     -H "Accept: application/json"

# 2. 创建一个新的预测任务（POST请求）
curl -X POST "https://api.supplychain.com/v1/forecasts/jobs" \
     -H "Authorization: Bearer <your_>" \
     -H "Content-Type: application/json" \
     -d '{
           "productId": 1001,
           "startDate": "2025-04-01",
           "endDate": "2025-06-30",
           "model": "ARIMA"
         }'

# 3. 更新预测单123的配置（PUT请求）
curl -X PUT "https://api.supplychain.com/v1/forecasts/123" \
     -H "Authorization: Bearer <your_>" \
     -H "Content-Type: application/json" \
     -d '{
           "productId": 1001,
           "model": "Prophet",
           "parameters": {
             "seasonality": "weekly"
           }
         }'

# 4. 删除预测任务456（DELETE请求）
curl -X DELETE "https://api.supplychain.com/v1/forecasts/jobs/456" \
     -H "Authorization: Bearer <your_>"

调试技巧： 使用 -v 参数（verbose）可以查看完整的请求和响应头信息，包括状态码、响应时间、缓存策略等，是定位网络层问题的利器。例如：curl -X GET -v "https://api.supplychain.com/v1/forecasts?productId=1001"

📚 课程目录

4. API基础概念：RESTful API设计原则、HTTP方法、状态码含义

4.1 RESTful API设计原则

4.2 HTTP方法（GET/POST/PUT/DELETE）

4.3 HTTP状态码含义

4.4 接口调试示例：使用cURL调用预测API

4.5 本章小结