lumina: Skill for Claude Code

Lumina API 接口设计规范

功能概述

本技能包用于确保 Lumina 框架项目的 REST API 设计符合规范，包括 URL 设计、HTTP 方法使用、统一响应格式、参数校验等。

RESTful API 设计规范

URL 设计

基础路径: /api/v1/{domain}

资源操作:
GET    /api/v1/agents              # 列表查询
GET    /api/v1/agents/{id}          # 详情查询
POST   /api/v1/agents              # 创建
PUT    /api/v1/agents/{id}          # 更新
DELETE /api/v1/agents/{id}          # 删除

特殊操作:
POST   /api/v1/agents/{id}/execute  # 执行 Agent
POST   /api/v1/agents/{id}/pause     # 暂停 Agent

HTTP 方法使用

统一响应格式

成功响应

{
  "code": 200,
  "msg": "操作成功",
  "data": { ... },
  "timestamp": 1704067200000
}

失败响应

{
  "code": 400,
  "msg": "参数错误",
  "data": null,
  "timestamp": 1704067200000,
  "errors": [
    {
      "field": "agentName",
      "message": "Agent名称不能为空"
    }
  ]
}

分页响应

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "list": [ ... ],
    "total": 100,
    "pageNum": 1,
    "pageSize": 10,
    "pages": 10
  },
  "timestamp": 1704067200000
}

状态码规范

DTO 设计规范

Request DTO

// 创建请求
@Data
@EqualsAndHashCode(callSuper = false)
public class CreateAgentDTO {
    
    @NotBlank(message = "Agent名称不能为空")
    @Size(max = 100, message = "Agent名称长度不能超过100")
    private String agentName;
    
    @NotNull(message = "Agent类型不能为空")
    private AgentTypeEnum agentType;
    
    @Size(max = 500, message = "描述长度不能超过500")
    private String description;
}

// 查询请求
@Data
@EqualsAndHashCode(callSuper = false)
public class QueryAgentDTO {
    
    private String agentName;
    
    private AgentTypeEnum agentType;
    
    @Min(value = 1, message = "页码必须大于0")
    private Integer pageNum = 1;
    
    @Min(value = 1, message = "每页数量必须大于0")
    @Max(value = 100, message = "每页数量不能超过100")
    private Integer pageSize = 10;
}