3. 接口设计原则

在资产台账移交接口开发中，遵循统一的接口设计原则是保障系统可维护性、可扩展性与团队协作效率的基础。本节围绕 RESTful API 设计规范，从资源命名、HTTP 方法选择、状态码使用三个核心维度展开，并结合资产移交场景给出具体示例。

3.1 RESTful API 设计规范概述

REST（Representational State Transfer）是一种基于资源的架构风格，核心约束包括：

• 无状态性：每个请求包含所有必要信息，服务端不保存客户端上下文。
• 统一接口：通过标准 HTTP 方法操作资源，资源通过 URI 唯一标识。
• 资源导向：将业务实体抽象为资源，而非操作或动作。
• 自描述消息：请求与响应中包含媒体类型、链接等信息，便于客户端理解。

3.2 资源命名规范

资源命名应遵循 名词复数形式、小写字母、连字符分隔 的原则，避免动词、下划线或驼峰命名。以下为资产移交场景的资源命名对照表：

3.3 HTTP 方法选择与语义

每个 HTTP 方法对应一种标准操作语义，在资产移交接口中应严格遵循：

3.4 接口设计原则流程关系

下图展示了资源命名、HTTP 方法与业务操作之间的映射关系，以及它们在资产移交流程中的位置：

3.5 接口设计示例：移交单创建与查询

以下代码展示符合 RESTful 原则的资产移交接口实现片段：

// 创建移交单（POST）
POST /api/v1/transfer-orders
Content-Type: application/json

{
  "sourceDepartment": "IT运维部",
  "targetDepartment": "资产管理中心",
  "transferDate": "2025-06-01",
  "assets": [
    {"assetId": "AST-2025-001", "warrantyId": "WAR-001"},
    {"assetId": "AST-2025-002", "warrantyId": "WAR-002"}
  ],
  "maintenancePlanIds": ["MP-2025-01", "MP-2025-02"]
}

// 响应：201 Created
{
  "id": "TO-2025-001",
  "status": "draft",
  "createdAt": "2025-06-01T10:30:00Z",
  "_links": {
    "self": {"href": "/api/v1/transfer-orders/TO-2025-001"},
    "assets": {"href": "/api/v1/transfer-orders/TO-2025-001/assets"}
  }
}

// 查询待处理移交单（GET）
GET /api/v1/transfer-orders?status=pending&page=1&size=20

// 响应：200 OK
{
  "totalItems": 45,
  "totalPages": 3,
  "currentPage": 1,
  "items": [
    {
      "id": "TO-2025-001",
      "status": "pending",
      "sourceDepartment": "IT运维部",
      "targetDepartment": "资产管理中心",
      "assetCount": 2
    }
  ],
  "_links": {
    "next": {"href": "/api/v1/transfer-orders?status=pending&page=2&size=20"},
    "prev": null
  }
}

3.6 状态码使用规范

资产移交接口应使用标准 HTTP 状态码表达操作结果，避免自定义状态码：