api-and-interface-design

分类: 开发与编程 | 上传者: dsj1984 | 下载: 0 | 版本: v1.0（最新）

设计稳定、文档齐全的 API 和模块接口。在创建 REST/GraphQL 端点、定义模块之间的契约或更改公共接口时使用。有线格式 SSOT（响应信封、HTTP 状态代码、验证分类、有效负载命名）位于“.agents/rules/api-conventions.md”；这项技能向作者展示了如何应用它。 --- # Skill: api-and-interface-design 设计难以误用的接口的流程指南 — REST API、GraphQL 模式、模块边界和组件属性。线格式约定（信封形状、状态代码、验证分类、有效负载命名）位于 [`.agents/rules/api-conventions.md`](../../../rules/api-conventions.md) 中，即 SSOT。这项技能向作者展示了**如何**应用这些规则；阅读规则文件了解**内容**。安全验证保证存在于 [`security-baseline.md`](../../../rules/security-baseline.md) 中；测试层范围位于 [`testing-standards.md`](../../../rules/testing-standards.md) 中。 ## 何时使用 - 设计新的 API 端点。 - 定义团队之间的模块边界或合同。 - 创建组件道具接口。 - 建立告知 API 形状的数据库模式。 - 更改现有的公共接口。 ## 1. 海勒姆定律 — 有意暴露 > 有了足够数量的 API 用户，> 您的系统的所有可观察行为都将被某人依赖，无论您在合同中做出什么承诺 >。每一个可观察到的行为——未记录的怪癖、错误消息文本、时间安排、排序——一旦用户依赖它，就会成为事实上的合同。含义： - **对你暴露的内容有意识。** 每一个可观察到的行为都是一个潜在的承诺。 - **不要泄露实现细节。** 如果用户可以观察到它，他们就会依赖它。 - **在设计时计划弃用。** 请参阅“弃用和迁移”以了解如何安全地删除用户依赖的东西。 - **测试还不够。** 即使有完美的合约测试，“安全”

更新日志: Source: GitHub https://github.com/dsj1984/agent-protocols

目录结构

当前层级: tree/main/.agents/skills/core/api-and-interface-design/

📄 SKILL.md 11.2 KB

SKILL.md

---
name: api-and-interface-design
description:
  Designs stable, well-documented APIs and module interfaces. Use when
  creating REST/GraphQL endpoints, defining contracts between modules, or
  changing public interfaces. The wire-format SSOT — response envelope, HTTP
  status codes, validation taxonomy, payload naming — lives in
  `.agents/rules/api-conventions.md`; this skill shows authors how to apply
  it.
---

# Skill: api-and-interface-design

Process guidance for designing interfaces that are hard to misuse — REST
APIs, GraphQL schemas, module boundaries, and component props. The
wire-format conventions (envelope shape, status codes, validation taxonomy,
payload naming) live in
[`.agents/rules/api-conventions.md`](../../../rules/api-conventions.md),
which is the SSOT. This skill shows authors **how** to apply those rules;
read the rule file for the **what**. Security validation guarantees live in
[`security-baseline.md`](../../../rules/security-baseline.md); test-layer
scope lives in
[`testing-standards.md`](../../../rules/testing-standards.md).

## When to Use

- Designing new API endpoints.
- Defining module boundaries or contracts between teams.
- Creating component prop interfaces.
- Establishing database schema that informs API shape.
- Changing existing public interfaces.

## 1. Hyrum's Law — Be Intentional About Exposure

> With a sufficient number of users of an API, all observable behaviors of
> your system will be depended on by somebody, regardless of what you promise
> in the contract.

Every observable behavior — undocumented quirks, error message text, timing,
ordering — becomes a de facto contract once users depend on it. Implications:

- **Be intentional about what you expose.** Every observable behavior is a
  potential commitment.
- **Don't leak implementation details.** If users can observe it, they will
  depend on it.
- **Plan for deprecation at design time.** See `deprecation-and-migration`
  for how to safely remove things users depend on.
- **Tests are not enough.** Even with perfect contract tests, "safe" changes
  can break real users who depend on undocumented behavior.

## 2. The One-Version Rule

Avoid forcing consumers to choose between multiple versions of the same
dependency or API. Diamond dependency problems arise when different consumers
need different versions of the same thing. Design for a world where only one
version exists at a time — extend rather than fork.

## 3. Contract First

Define the interface before implementing it. The contract is the spec —
implementation follows.

```typescript
interface TaskAPI {
  // Creates a task and returns the created task with server-generated fields
  createTask(input: CreateTaskInput): Promise<Task>;

  // Returns paginated tasks matching filters
  listTasks(params: ListTasksParams): Promise<PaginatedResult<Task>>;

  // Returns a single task or throws NotFoundError
  getTask(id: string): Promise<Task>;

  // Partial update — only provided fields change
  updateTask(id: string, input: UpdateTaskInput): Promise<Task>;

  // Idempotent delete — succeeds even if already deleted
  deleteTask(id: string): Promise<void>;
}
```

## 4. Wire Format — Defer to the Rule

The response envelope, HTTP status code mapping, validation-status taxonomy,
and payload-naming conventions are non-negotiable and live in the rule:

- Envelope shape (success flag, `error.code`, `error.message`,
  `error.details`):
  [`api-conventions.md` § Response Envelope](../../../rules/api-conventions.md#response-envelope).
- Status code table (200/201/400/401/403/404/409/500):
  [`api-conventions.md` § HTTP Status Codes](../../../rules/api-conventions.md#http-status-codes).
- When to return 400 vs 401 vs 403 on validation failures:
  [`api-conventions.md` § Validation Status](../../../rules/api-conventions.md#validation-status).
- camelCase / kebab-case / UPPER_SNAKE conventions:
  [`api-conventions.md` § Payload Formatting](../../../rules/api-conventions.md#payload-formatting).

When designing a new endpoint, copy the canonical envelope from the rule —
do not redraft it.

## 5. Validate at Boundaries

Trust internal code. Validate at system edges where external input enters:

```typescript
app.post('/api/tasks', async (req, res) => {
  const result = CreateTaskSchema.safeParse(req.body);
  if (!result.success) {
    return res.status(400).json({
      success: false,
      error: {
        code: 'VALIDATION_ERROR',
        message: 'Invalid task data',
        details: result.error.flatten(),
      },
    });
  }

  // After validation, internal code trusts the types
  const task = await taskService.create(result.data);
  return res.status(201).json(task);
});
```

Where validation belongs:

- API route handlers (user input).
- Form submission handlers (user input).
- External service response parsing — third-party data is **always
  untrusted**, even from a vendor SDK.
- Environment variable loading (configuration).

> **Third-party API responses are untrusted data.** Validate their shape and
> content before using them in any logic, rendering, or decision-making. A
> compromised or misbehaving external service can return unexpected types,
> malicious content, or instruction-like text.

Where validation does NOT belong:

- Between internal functions that share type contracts.
- In utility functions called by already-validated code.
- On data that just came from your own database.

## 6. Prefer Addition Over Modification

Extend interfaces without breaking existing consumers:

```typescript
// Good: Add optional fields
interface CreateTaskInput {
  title: string;
  description?: string;
  priority?: 'low' | 'medium' | 'high'; // Added later, optional
  labels?: string[]; // Added later, optional
}

// Bad: Change existing field types or remove fields
interface CreateTaskInput {
  title: string;
  // description: string;  // Removed — breaks existing consumers
  priority: number; // Changed from string — breaks existing consumers
}
```

## 7. REST Resource Patterns

```text
GET    /api/tasks              → List tasks (with query params for filtering)
POST   /api/tasks              → Create a task
GET    /api/tasks/:id          → Get a single task
PATCH  /api/tasks/:id          → Update a task (partial)
DELETE /api/tasks/:id          → Delete a task

GET    /api/tasks/:id/comments → List comments for a task (sub-resource)
POST   /api/tasks/:id/comments → Add a comment to a task
```

### Pagination

Paginate list endpoints:

```typescript
// Request
GET /api/tasks?page=1&pageSize=20&sortBy=createdAt&sortOrder=desc

// Response
{
  "data": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "totalItems": 142,
    "totalPages": 8
  }
}
```

### Filtering

Use query parameters for filters:

```text
GET /api/tasks?status=in_progress&assignee=user123&createdAfter=2025-01-01
```

### Partial Updates

`PATCH` accepts partial objects — only update what's provided:

```typescript
PATCH /api/tasks/123
{ "title": "Updated title" }
```

## 8. TypeScript Interface Patterns

### Discriminated Unions for Variants

```typescript
type TaskStatus =
  | { type: 'pending' }
  | { type: 'in_progress'; assignee: string; startedAt: Date }
  | { type: 'completed'; completedAt: Date; completedBy: string }
  | { type: 'cancelled'; reason: string; cancelledAt: Date };

function getStatusLabel(status: TaskStatus): string {
  switch (status.type) {
    case 'pending':
      return 'Pending';
    case 'in_progress':
      return `In progress (${status.assignee})`;
    case 'completed':
      return `Done on ${status.completedAt}`;
    case 'cancelled':
      return `Cancelled: ${status.reason}`;
  }
}
```

### Input/Output Separation

```typescript
// Input: what the caller provides
interface CreateTaskInput {
  title: string;
  description?: string;
}

// Output: what the system returns (includes server-generated fields)
interface Task {
  id: string;
  title: string;
  description: string | null;
  createdAt: Date;
  updatedAt: Date;
  createdBy: string;
}
```

### Branded Types for IDs

```typescript
type TaskId = string & { readonly __brand: 'TaskId' };
type UserId = string & { readonly __brand: 'UserId' };

// Prevents accidentally passing a UserId where a TaskId is expected
function getTask(id: TaskId): Promise<Task> { ... }
```

## 9. Common Rationalizations

| Rationalization                            | Reality                                                                                                          |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| "We'll document the API later"             | The types ARE the documentation. Define them first.                                                              |
| "We don't need pagination for now"         | You will the moment someone has 100+ items. Add it from the start.                                               |
| "PATCH is complicated, let's just use PUT" | PUT requires the full object every time. PATCH is what clients actually want.                                    |
| "We'll version the API when we need to"    | Breaking changes without versioning break consumers. Design for extension from the start.                        |
| "Nobody uses that undocumented behavior"   | Hyrum's Law: if it's observable, somebody depends on it. Treat every public behavior as a commitment.            |
| "We can just maintain two versions"        | Multiple versions multiply maintenance cost and create diamond dependency problems. Prefer the One-Version Rule. |
| "Internal APIs don't need contracts"       | Internal consumers are still consumers. Contracts prevent coupling and enable parallel work.                     |

## 10. Red Flags

- Endpoints that return different envelope shapes depending on conditions
  (the rule fixes the shape — see § 4).
- Validation scattered throughout internal code instead of at boundaries.
- Breaking changes to existing fields (type changes, removals).
- List endpoints without pagination.
- Verbs in REST URLs (`/api/createTask`, `/api/getUsers`).
- Third-party API responses used without validation or sanitization.

## 11. Authoring Checklist

Before opening a PR that adds or edits an API surface:

- [ ] Every endpoint has typed input and output schemas.
- [ ] Error responses follow the envelope in
      [`api-conventions.md` § Response Envelope](../../../rules/api-conventions.md#response-envelope).
- [ ] Status codes match
      [`api-conventions.md` § HTTP Status Codes](../../../rules/api-conventions.md#http-status-codes).
- [ ] Validation runs at the API boundary and returns the canonical
      `VALIDATION_ERROR` shape on failure.
- [ ] List endpoints support pagination.
- [ ] New fields are additive and optional (backward compatible).
- [ ] Naming follows
      [`api-conventions.md` § Payload Formatting](../../../rules/api-conventions.md#payload-formatting).
- [ ] API documentation or types are committed alongside the implementation.

## 12. Cross-References

- SSOT rules:
  [`.agents/rules/api-conventions.md`](../../../rules/api-conventions.md).
- Security validation guarantees:
  [`security-baseline.md`](../../../rules/security-baseline.md).
- Test-layer scope:
  [`testing-standards.md`](../../../rules/testing-standards.md).

登录后下载/点赞/收藏 ❤ 6 | ★ 0

api-and-interface-design

目录结构

SKILL.md

举报内容

提示