4. 金融特征平台API设计原则：RESTful风格、幂等性设计、批量查询与单点查询的权衡、超时与重试策略

金融特征平台的API是连接在线推理与离线特征计算的桥梁。API设计质量直接影响特征服务的可用性、数据一致性和运维成本。本章围绕四个核心设计原则展开：RESTful风格确保接口可理解性与标准化；幂等性设计保障重复请求不产生副作用；批量查询与单点查询的权衡平衡性能与灵活性；超时与重试策略防范级联故障。

4.1 RESTful风格：资源导向的接口设计

金融特征平台将特征视为资源，采用RESTful风格定义端点。核心资源包括：特征实体（Feature）、特征视图（FeatureView）、特征服务（FeatureService）。每个资源通过标准HTTP动词操作。

RESTful设计的关键约束：

• 版本号放在路径中：/api/v1/ 而非请求头，便于网关路由与缓存。
• 复数名词表示资源集合：/features 而非 /feature。
• 查询参数用于过滤与分页：?status=active&page=1&size=20。
• 错误响应使用标准HTTP状态码：200（成功）、400（参数错误）、404（特征不存在）、409（版本冲突）、429（限流）、500（服务端异常）。

4.2 幂等性设计：防止重复请求的副作用

金融场景中，网络抖动、客户端重试、消息队列重复投递都可能导致同一请求被处理多次。幂等性设计确保无论请求执行一次还是多次，系统状态保持一致。

幂等性实现策略：

• 自然幂等（GET/PUT/DELETE）：查询、全量更新、删除操作天然幂等，重复执行结果不变。
• 请求ID幂等键（Idempotency-Key）：对POST等非幂等方法，客户端在请求头中携带唯一键（UUID），服务端缓存处理结果，重复请求直接返回缓存。
• 乐观锁（版本号）：更新特征定义时携带 expected_version，版本不匹配则拒绝更新，避免覆盖。
• 去重表（Deduplication Table）：在数据库层记录已处理的请求ID，设置TTL自动清理。

4.3 批量查询与单点查询的权衡

特征平台的核心查询场景是：给定实体ID列表，返回对应的特征值。单点查询（一次一个实体）与批量查询（一次多个实体）各有优劣，需根据业务场景权衡。

单点查询（Point Query）：

• 优点：延迟低（P99 < 10ms）、缓存命中率高、错误隔离性好（一个失败不影响其他）。
• 缺点：连接开销大（每个请求建立连接）、吞吐量受限（受限于连接数）。
• 适用场景：实时风控、交易决策等对延迟极度敏感且请求量可控的场景。

批量查询（Batch Query）：

• 优点：连接复用、吞吐量高（单次请求可查询数百实体）、网络开销小。
• 缺点：延迟受最慢实体影响（木桶效应）、部分失败处理复杂、缓存利用率低。
• 适用场景：批量特征计算、离线特征回溯、推荐系统召回阶段。

权衡建议：

• 在线推理场景优先使用单点查询，配合连接池与HTTP/2多路复用缓解连接开销。
• 离线/批量场景使用批量查询，但限制单次批量大小（建议≤200实体），并支持分页。
• 提供统一查询接口：POST /api/v1/feature-values:batchGet 接受实体ID列表，返回Map结构；同时保留单点查询端点 GET /api/v1/feature-values/{entity_id}。

4.4 超时与重试策略：防范级联故障

金融特征平台是典型的高依赖链系统：客户端 → API网关 → 特征服务 → 特征存储（Redis/MySQL/对象存储）。任一环节的延迟抖动都可能引发级联超时与资源耗尽。

超时策略：

• 连接超时（Connect Timeout）：建议 500ms，超过则快速失败，避免占用连接池。
• 读取超时（Read Timeout）：建议 2s（单点查询）/ 5s（批量查询），根据P99延迟动态调整。
• 写入超时（Write Timeout）：建议 1s，特征写入通常要求低延迟。
• 全链路超时（End-to-End Timeout）：客户端总超时 = 连接超时 + 读取超时 × 重试次数，建议不超过 10s。

重试策略：

• 指数退避（Exponential Backoff）：初始间隔 100ms，退避因子 2，最大间隔 5s。
• 抖动（Jitter）：在退避间隔上增加随机 ±50% 抖动，避免惊群效应。
• 重试次数限制：最多 3 次，超过则返回失败。
• 仅重试幂等请求：GET/PUT/DELETE 可重试；POST 仅在携带幂等键时可重试。

代码示例：带指数退避与抖动的重试逻辑（Java伪代码）

public class RetryStrategy {
    private static final int MAX_RETRIES = 3;
    private static final long BASE_DELAY_MS = 100;
    private static final long MAX_DELAY_MS = 5000;

    public Response callWithRetry(Supplier<Response> request, String idempotencyKey) {
        Response response = null;
        for (int attempt = 0; attempt <= MAX_RETRIES; attempt++) {
            try {
                response = request.get();
                if (response.isSuccess()) {
                    return response;
                }
                // 仅重试 5xx 和 429
                if (response.getStatusCode() < 500 && response.getStatusCode() != 429) {
                    return response;
                }
            } catch (TimeoutException e) {
                // 超时异常，继续重试
            }
            if (attempt < MAX_RETRIES) {
                long delay = calculateBackoffWithJitter(attempt);
                Thread.sleep(delay);
            }
        }
        return Response.failure("Max retries exceeded");
    }

    private long calculateBackoffWithJitter(int attempt) {
        long baseDelay = BASE_DELAY_MS * (long) Math.pow(2, attempt);
        long cappedDelay = Math.min(baseDelay, MAX_DELAY_MS);
        // 添加 ±50% 抖动
        double jitter = 0.5 + Math.random();
        return (long) (cappedDelay * jitter);
    }
}