跳至主要內容

附录B: API接口文档示例

老马啸西风2025/9/7大约 7 分钟GouTongGouTong

在企业级统一通知通道平台的建设中，标准化的API接口设计是确保平台易用性、可扩展性和可维护性的关键。本文档提供了统一通知平台核心API接口的详细说明，包括接口规范、请求参数、响应格式、错误处理等，为开发者提供清晰的接入指导。

API设计原则

统一通知平台的API设计遵循以下核心原则：

RESTful设计风格

  1. 资源导向：以资源为核心设计API，每个资源有明确的URI标识
  2. HTTP方法映射：使用标准HTTP方法（GET、POST、PUT、DELETE）操作资源
  3. 无状态性：每个请求包含完整信息，服务器不保存客户端状态
  4. 统一接口：提供一致的接口设计和错误处理机制

版本化管理

  1. URI版本控制：通过URI路径管理API版本（如/v1/notifications）
  2. 向后兼容：新版本保持对旧版本的兼容性
  3. 废弃策略：明确的API废弃和迁移策略

安全性保障

  1. 身份认证：基于API Key的身份认证机制
  2. 权限控制：细粒度的权限控制和访问限制
  3. 数据加密：敏感数据传输加密
  4. 请求签名：防止请求篡改和重放攻击

核心API接口

消息发送接口

接口描述

发送各类通知消息，支持短信、邮件、推送等多种通道。

请求URL

POST /v1/notifications/send

请求头

Content-Type: application/json
Authorization: Bearer {access_token}
X-API-Key: {api_key}
X-Timestamp: {timestamp}
X-Signature: {signature}

请求参数

{
  "request_id": "string",           // 请求唯一标识，用于幂等性控制
  "sender": "string",              // 发送方标识
  "receivers": [                   // 接收者列表
    {
      "type": "sms|email|push",    // 接收者类型
      "address": "string",         // 接收地址（手机号、邮箱、设备标识等）
      "user_id": "string",         // 用户ID（可选）
      "params": {                  // 模板参数
        "key": "value"
      }
    }
  ],
  "template_id": "string",         // 模板ID
  "channel": "sms|email|push",     // 指定通道类型（可选）
  "priority": "high|normal|low",   // 消息优先级
  "scheduled_time": "timestamp",   // 定时发送时间（可选）
  "callback_url": "string",        // 回调地址（可选）
  "metadata": {                    // 元数据（可选）
    "business_type": "string",
    "trace_id": "string"
  }
}

响应格式

{
  "code": 0,                       // 响应码，0表示成功
  "message": "success",            // 响应消息
  "data": {
    "request_id": "string",        // 请求ID
    "task_id": "string",           // 任务ID
    "status": "accepted|rejected", // 处理状态
    "details": [                   // 详细处理结果
      {
        "receiver": "string",      // 接收者
        "channel": "string",       // 通道类型
        "status": "success|fail",  // 发送状态
        "message_id": "string",    // 消息ID
        "error_code": "string",    // 错误码（失败时）
        "error_message": "string"  // 错误信息（失败时）
      }
    ]
  }
}

错误码

错误码错误信息描述
0success请求成功
1001invalid_parameter参数无效
1002template_not_found模板不存在
1003channel_not_supported通道不支持
1004receiver_invalid接收者无效
1005rate_limit_exceeded频率限制超出
1006authentication_failed认证失败
1007permission_denied权限不足
1008internal_error内部错误

消息查询接口

接口描述

查询消息发送状态和详细信息。

请求URL

GET /v1/notifications/{message_id}

请求参数

message_id: string (path parameter)  // 消息ID

响应格式

{
  "code": 0,
  "message": "success",
  "data": {
    "message_id": "string",          // 消息ID
    "request_id": "string",          // 请求ID
    "sender": "string",              // 发送方
    "receiver": "string",            // 接收者
    "channel": "string",             // 通道类型
    "template_id": "string",         // 模板ID
    "content": "string",             // 发送内容
    "status": "sent|delivered|failed|pending", // 当前状态
    "created_time": "timestamp",     // 创建时间
    "sent_time": "timestamp",        // 发送时间
    "delivered_time": "timestamp",   // 送达时间
    "error_code": "string",          // 错误码
    "error_message": "string",       // 错误信息
    "metadata": {                    // 元数据
      "business_type": "string",
      "trace_id": "string"
    }
  }
}

批量发送接口

接口描述

支持批量发送相同模板的消息给多个接收者。

请求URL

POST /v1/notifications/batch-send

请求参数

{
  "request_id": "string",
  "sender": "string",
  "receivers": [
    {
      "type": "sms|email|push",
      "address": "string",
      "user_id": "string",
      "params": {
        "key": "value"
      }
    }
  ],
  "template_id": "string",
  "channel": "sms|email|push",
  "priority": "high|normal|low",
  "scheduled_time": "timestamp",
  "callback_url": "string"
}

响应格式

{
  "code": 0,
  "message": "success",
  "data": {
    "request_id": "string",
    "task_id": "string",
    "status": "accepted",
    "total_count": 0,                // 总接收者数
    "success_count": 0,              // 成功数
    "fail_count": 0,                 // 失败数
    "details": [
      {
        "receiver": "string",
        "channel": "string",
        "status": "success|fail",
        "message_id": "string",
        "error_code": "string",
        "error_message": "string"
      }
    ]
  }
}

SDK使用示例

Java SDK示例

// 初始化客户端
NotificationClient client = new NotificationClient.Builder()
    .endpoint("https://api.notification-platform.com")
    .apiKey("your-api-key")
    .build();

// 构造发送请求
SendRequest request = SendRequest.builder()
    .requestId(UUID.randomUUID().toString())
    .sender("system")
    .receivers(Arrays.asList(
        Receiver.builder()
            .type(ChannelType.SMS)
            .address("13800138000")
            .params(Collections.singletonMap("code", "123456"))
            .build()
    ))
    .templateId("sms_verification_code")
    .priority(Priority.HIGH)
    .build();

// 发送消息
SendResponse response = client.send(request);
if (response.isSuccess()) {
    System.out.println("消息发送成功，任务ID: " + response.getTaskId());
} else {
    System.err.println("消息发送失败: " + response.getMessage());
}

Python SDK示例

from notification_sdk import NotificationClient

# 初始化客户端
client = NotificationClient(
    endpoint="https://api.notification-platform.com",
    api_key="your-api-key"
)

# 构造发送请求
request = {
    "request_id": "req_123456",
    "sender": "system",
    "receivers": [
        {
            "type": "sms",
            "address": "13800138000",
            "params": {
                "code": "123456"
            }
        }
    ],
    "template_id": "sms_verification_code",
    "priority": "high"
}

# 发送消息
response = client.send(request)
if response["code"] == 0:
    print(f"消息发送成功，任务ID: {response['data']['task_id']}")
else:
    print(f"消息发送失败: {response['message']}")

回调接口规范

回调地址配置

在发送消息时可以指定回调地址，平台将在消息状态发生变化时主动回调通知。

回调请求格式

POST {callback_url}
Content-Type: application/json
X-Callback-Signature: {signature}
{
  "event_type": "message_status_changed",  // 事件类型
  "timestamp": "timestamp",                // 事件时间
  "data": {
    "message_id": "string",                // 消息ID
    "request_id": "string",                // 请求ID
    "status": "sent|delivered|failed",     // 当前状态
    "channel": "string",                   // 通道类型
    "receiver": "string",                  // 接收者
    "sent_time": "timestamp",              // 发送时间
    "delivered_time": "timestamp",         // 送达时间
    "error_code": "string",                // 错误码
    "error_message": "string"              // 错误信息
  }
}

回调响应要求

回调接收方需要在收到回调请求后返回HTTP 200状态码，表示接收成功。如果返回其他状态码或超时，平台将按策略进行重试。

错误处理机制

错误码分类

  1. 参数错误（1000-1999）：请求参数不符合要求
  2. 认证错误（2000-2999）：身份认证或权限相关错误
  3. 业务错误（3000-3999）：业务逻辑相关错误
  4. 系统错误（5000-5999）：服务器内部错误

重试机制

  1. 客户端重试：对于网络错误或临时性错误，客户端应实现指数退避重试
  2. 服务端重试：对于回调失败，服务端将按策略进行重试（最多3次）

幂等性保证

通过request_id参数保证请求的幂等性，相同request_id的重复请求将返回相同结果而不重复处理。

安全最佳实践

认证安全

  1. API Key管理：定期轮换API Key，避免泄露
  2. 请求签名：对重要请求进行签名验证
  3. HTTPS传输：所有API调用必须通过HTTPS进行

数据安全

  1. 敏感信息脱敏：日志中不记录敏感信息
  2. 数据加密存储：敏感数据加密存储
  3. 访问控制：基于角色的访问控制（RBAC）

监控告警

  1. 异常访问监控：监控异常访问模式
  2. 安全事件告警：及时发现和响应安全事件
  3. 审计日志：完整记录所有API访问日志

性能优化建议

请求优化

  1. 批量操作：优先使用批量接口减少请求次数
  2. 连接复用：使用HTTP连接池复用连接
  3. 异步处理：对于非实时性要求高的场景使用异步发送

响应优化

  1. 缓存机制：合理使用缓存减少数据库查询
  2. 分页查询：大数据量查询使用分页
  3. 字段精简：只返回必要的字段信息

结语

标准化的API接口设计是统一通知平台成功的关键因素之一。通过遵循RESTful设计原则、实施安全最佳实践、提供完善的文档和SDK，我们可以为开发者提供简单、高效、安全的接入体验。

在实际应用中，建议根据具体业务需求和安全要求，合理配置API参数和权限控制。同时，要建立完善的监控和告警机制，及时发现和处理API使用中的问题。

随着业务的发展和技术的进步，API设计也需要不断优化和完善。我们应该保持对新技术和新标准的关注，持续改进API设计，确保平台的先进性和竞争力。

我是老马，期待与你的下次重逢
Copyright © 2025 老马啸西风