endpoint-validator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Endpoint Validator Skill

Endpoint Validator 技能

Operator Context

运行上下文

This skill operates as an operator for API endpoint validation workflows, configuring Claude's behavior for deterministic, structured health checking. It implements the Discover, Validate, Report pattern -- find endpoints, test each against expectations, produce machine-readable results with clear pass/fail verdicts.

本技能作为API端点验证工作流的操作器，配置Claude的行为以实现确定性、结构化的健康检查。它采用Discover、Validate、Report模式——查找端点，根据预期逐一测试，生成带有明确通过/失败结论的机器可读结果。

Hardcoded Behaviors (Always Apply)

硬编码行为（始终生效）

Read-Only by Default: Only makes GET requests unless explicitly configured otherwise
Timeout Safety: Default 5-second timeout per request prevents hanging
Structured Output: Always produces machine-parseable results with exit codes
No Data Mutation: Never sends POST/PUT/DELETE without explicit user configuration
CLAUDE.md Compliance: Read and follow repository CLAUDE.md before validation

默认只读模式：除非明确配置，否则仅发送GET请求
超时安全机制：默认每个请求5秒超时，防止挂起
结构化输出：始终生成带有退出码的机器可解析结果
无数据变更：未经用户明确配置，绝不发送POST/PUT/DELETE请求
CLAUDE.md 合规性：验证前读取并遵循仓库中的CLAUDE.md文件

Default Behaviors (ON unless disabled)

默认行为（默认开启，可关闭）

Progress Display: Show each endpoint result as it completes
Summary Statistics: Pass/fail counts and percentages at end of run
Timing Information: Response time in milliseconds for every endpoint
Threshold Enforcement: Flag endpoints exceeding configured max_time
Sequential Execution: Test endpoints one at a time for predictable output

进度展示：完成每个端点测试后立即显示结果
统计摘要：测试结束时展示通过/失败数量及占比
计时信息：记录每个端点的响应时间（毫秒级）
阈值校验：标记超出配置max_time的端点
串行执行：逐个测试端点，确保输出可预测

Optional Behaviors (OFF unless enabled)

可选行为（默认关闭，可开启）

POST/PUT/DELETE Testing: Requires explicit method + body in configuration
Authentication Headers: Bearer tokens or basic auth passed via config
Response Body Validation: Deep JSON key checking beyond top-level
Custom Headers: Additional headers per endpoint (e.g., Accept, Content-Type)
Parallel Requests: Test multiple endpoints concurrently

POST/PUT/DELETE测试：需在配置中明确指定方法和请求体
认证头信息：通过配置传递Bearer令牌或基础认证信息
响应体验证：对JSON进行顶层键之外的深度检查
自定义请求头：为每个端点添加额外请求头（如Accept、Content-Type）
并行请求：同时测试多个端点

What This Skill CAN Do

本技能可实现的功能

Validate HTTP GET endpoints for expected status codes
Check JSON responses contain expected top-level keys
Measure and report response times per endpoint
Detect slow endpoints exceeding configured thresholds
Produce CI/CD compatible exit codes (0 = all pass, 1 = any fail)
Read endpoint definitions from JSON config files

验证HTTP GET端点是否返回预期状态码
检查JSON响应是否包含预期的顶层键
测量并报告每个端点的响应时间
检测超出配置阈值的慢端点
生成CI/CD兼容的退出码（0=全部通过，1=存在失败）
从JSON配置文件读取端点定义

What This Skill CANNOT Do

本技能无法实现的功能

Perform load or stress testing (single request per endpoint only)
Execute browser-based or JavaScript-rendered tests
Handle OAuth flows or multi-step authentication chains
Validate full JSON schemas (top-level key presence only)
Test WebSocket or gRPC endpoints (HTTP only)

执行负载或压力测试（每个端点仅发送一次请求）
执行基于浏览器或JavaScript渲染的测试
处理OAuth流程或多步认证链
验证完整JSON schema（仅检查顶层键是否存在）
测试WebSocket或gRPC端点（仅支持HTTP）

Instructions

操作步骤

Phase 1: DISCOVER

阶段1：DISCOVER（发现）

Goal: Locate or receive endpoint definitions before making any requests.

Step 1: Search for endpoint configuration

Look for definitions in priority order:

```
endpoints.json
```
in project root
```
tests/endpoints.json
```
Inline specification provided by user or calling agent

Step 2: Parse and validate configuration

Configuration must contain

base_url

and at least one endpoint:

json

{
  "base_url": "http://localhost:8000",
  "endpoints": [
    {"path": "/health", "expect_status": 200},
    {"path": "/api/v1/users", "expect_key": "data", "timeout": 10},
    {"path": "/api/v1/search?q=test", "max_time": 2.0}
  ]
}

Each endpoint supports these fields:

```
path
```
(required): URL path appended to base_url
```
expect_status
```
(default: 200): Expected HTTP status code
```
expect_key
```
(optional): Top-level JSON key that must exist in response
```
timeout
```
(default: 5): Request timeout in seconds
```
max_time
```
(optional): Fail if response exceeds this threshold in seconds

Step 3: Confirm base URL is reachable

Make a single request to

base_url

before running the full suite. If unreachable, report immediately rather than failing every endpoint individually.

Gate: Configuration parsed, base URL reachable, at least one endpoint defined. Proceed only when gate passes.

目标：在发送任何请求前，定位或接收端点定义。

步骤1：搜索端点配置

按以下优先级查找定义：

项目根目录下的
```
endpoints.json
```
```
tests/endpoints.json
```
用户或调用Agent提供的内联规范

步骤2：解析并验证配置

配置必须包含

base_url

和至少一个端点：

json

{
  "base_url": "http://localhost:8000",
  "endpoints": [
    {"path": "/health", "expect_status": 200},
    {"path": "/api/v1/users", "expect_key": "data", "timeout": 10},
    {"path": "/api/v1/search?q=test", "max_time": 2.0}
  ]
}

每个端点支持以下字段：

```
path
```
（必填）：追加到base_url后的URL路径
```
expect_status
```
（默认值：200）：预期的HTTP状态码
```
expect_key
```
（可选）：响应JSON中必须存在的顶层键
```
timeout
```
（默认值：5）：请求超时时间（秒）
```
max_time
```
（可选）：如果响应时间超过该阈值，则标记为失败

步骤3：确认基础URL可达

在运行完整测试套件前，先向

base_url

发送一次请求。如果无法访问，立即报告，而非让所有端点测试都失败。

关卡要求：配置解析完成、基础URL可达、至少定义了一个端点。仅当满足条件时，才可进入下一阶段。

Phase 2: VALIDATE

阶段2：VALIDATE（验证）

Goal: Test each endpoint against its expected criteria and collect structured results.

Step 1: Execute requests sequentially

For each endpoint:

Construct full URL from
```
base_url
```
+
```
path
```
Send GET request with configured timeout
Record status code, response time, and body

Step 2: Evaluate against expectations

For each response, check in order:

Status code: Does it match
```
expect_status
```
? If not, mark FAIL.
JSON key: If
```
expect_key
```
set, parse JSON and check key exists. If missing or not valid JSON, mark FAIL.
Response time: If
```
max_time
```
set and elapsed exceeds it, mark SLOW.
Security headers: Check response headers for common security headers. Report missing headers as WARN (not FAIL):
- ```
Strict-Transport-Security
```
  — HSTS enforcement (expected on HTTPS endpoints)
- ```
Content-Security-Policy
```
  — XSS mitigation
- ```
X-Content-Type-Options
```
  — should be
```
nosniff
```
- ```
X-Frame-Options
```
  — clickjacking prevention (or CSP
```
frame-ancestors
```
  )

Skip security header checks for localhost/127.0.0.1 endpoints (development environments don't typically set these). Only check on non-localhost base URLs unless explicitly configured.

Step 3: Handle failures gracefully

Connection refused: Record as FAIL with "Connection refused" error
Timeout exceeded: Record as FAIL with "Timeout after Ns" error
Invalid JSON when
```
expect_key
```
set: Record as FAIL with "Invalid JSON response"
Unexpected exception: Record as FAIL with exception message

Gate: All endpoints tested. Every result has a clear PASS, FAIL, or SLOW verdict. Proceed only when gate passes.

目标：根据预期标准测试每个端点，并收集结构化结果。

步骤1：串行执行请求

对每个端点执行以下操作：

从
```
base_url
```
+
```
path
```
构造完整URL
发送带有配置超时时间的GET请求
记录状态码、响应时间和响应体

步骤2：根据预期标准评估结果

按以下顺序检查每个响应：

状态码：是否与
```
expect_status
```
匹配？若不匹配，标记为FAIL（失败）。
JSON键：如果设置了
```
expect_key
```
，解析JSON并检查该键是否存在。若缺失或响应不是有效JSON，标记为FAIL。
响应时间：如果设置了
```
max_time
```
且实际耗时超过该值，标记为SLOW（缓慢）。
安全头信息：检查响应头中是否包含常见安全头。缺失的头信息标记为WARN（警告，而非失败）：
- ```
Strict-Transport-Security
```
  — HSTS强制（HTTPS端点预期存在）
- ```
Content-Security-Policy
```
  — XSS防护
- ```
X-Content-Type-Options
```
  — 应设置为
```
nosniff
```
- ```
X-Frame-Options
```
  — 点击劫持防护（或CSP的
```
frame-ancestors
```
  ）

跳过对localhost/127.0.0.1端点的安全头检查（开发环境通常不设置这些头）。仅对非本地基础URL进行检查，除非明确配置强制检查。

步骤3：优雅处理失败场景

连接被拒绝：记录为FAIL，错误信息为"Connection refused"
超时：记录为FAIL，错误信息为"Timeout after Ns"
设置
```
expect_key
```
但响应不是有效JSON：记录为FAIL，错误信息为"Invalid JSON response"
意外异常：记录为FAIL，错误信息为异常详情

关卡要求：所有端点均已测试，每个结果都有明确的PASS（通过）、FAIL或SLOW结论。仅当满足条件时，才可进入下一阶段。

Phase 3: REPORT

阶段3：REPORT（报告）

Goal: Produce structured, machine-readable output with summary statistics.

Step 1: Format individual results

ENDPOINT VALIDATION REPORT
==========================
Base URL: http://localhost:8000
Endpoints: 15 tested

RESULTS:
  /api/health                    200 OK      45ms
  /api/users                     200 OK     123ms
  /api/products                  500 FAIL   "Internal Server Error"
  /api/slow                      200 SLOW   3.2s > 2.0s threshold

SECURITY HEADERS (non-localhost only):
  /api/health                    WARN  Missing: Content-Security-Policy, X-Frame-Options
  /api/users                     OK    All security headers present
  /api/products                  SKIP  (endpoint failed)

Step 2: Produce summary

SUMMARY:
  Passed: 13/15 (86.7%)
  Failed: 1 (status error)
  Slow: 1 (exceeded threshold)
  Security header warnings: 3 endpoints missing headers

Step 3: Set exit code

Exit 0 if all endpoints passed (SLOW counts as pass unless
```
max_time
```
was set)
Exit 1 if any endpoint failed

Gate: Report printed, exit code set. Validation complete.

目标：生成结构化、机器可读的输出及统计摘要。

步骤1：格式化单个结果

ENDPOINT VALIDATION REPORT
==========================
Base URL: http://localhost:8000
Endpoints: 15 tested

RESULTS:
  /api/health                    200 OK      45ms
  /api/users                     200 OK     123ms
  /api/products                  500 FAIL   "Internal Server Error"
  /api/slow                      200 SLOW   3.2s > 2.0s threshold

SECURITY HEADERS (non-localhost only):
  /api/health                    WARN  Missing: Content-Security-Policy, X-Frame-Options
  /api/users                     OK    All security headers present
  /api/products                  SKIP  (endpoint failed)

步骤2：生成统计摘要

SUMMARY:
  Passed: 13/15 (86.7%)
  Failed: 1 (status error)
  Slow: 1 (exceeded threshold)
  Security header warnings: 3 endpoints missing headers

步骤3：设置退出码

如果所有端点通过，退出码为0（SLOW仅在设置
```
max_time
```
时才视为失败）
如果存在任何端点失败，退出码为1

关卡要求：报告已生成，退出码已设置。验证流程完成。

Examples

示例

Example 1: Pre-Deployment Health Check

示例1：部署前健康检查

User says: "Validate all endpoints before we deploy" Actions:

Find
```
endpoints.json
```
in project root (DISCOVER)
Test each endpoint, collect status codes and times (VALIDATE)
Print report, exit 0 if all pass (REPORT) Result: Structured pass/fail report with CI-compatible exit code

用户指令："部署前验证所有端点" 操作步骤：

查找项目根目录下的
```
endpoints.json
```
（DISCOVER阶段）
测试每个端点，收集状态码和响应时间（VALIDATE阶段）
生成报告，若全部通过则退出码为0（REPORT阶段）结果：生成结构化的通过/失败报告，以及CI兼容的退出码

Example 2: Smoke Test After Migration

示例2：迁移后冒烟测试

User says: "Check if the API is still working after the database migration" Actions:

Read endpoint config, confirm base URL reachable (DISCOVER)
Hit each endpoint, check status and expected keys (VALIDATE)
Surface any failures with error details (REPORT) Result: Quick verification that migration did not break API contracts

用户指令："数据库迁移后检查API是否仍正常工作" 操作步骤：

读取端点配置，确认基础URL可达（DISCOVER阶段）
请求每个端点，检查状态码和预期键（VALIDATE阶段）
展示所有失败的端点及错误详情（REPORT阶段）结果：快速验证迁移是否未破坏API契约

Error Handling

错误处理

Error: "Base URL Unreachable"

错误："Base URL Unreachable"

Cause: Service not running, wrong port, or network issue Solution:

Verify service is running (
```
ps aux
```
,
```
docker ps
```
, or equivalent)
Confirm port matches config (
```
netstat -tlnp
```
or
```
ss -tlnp
```
)
Check for firewall rules or container networking issues

原因：服务未运行、端口错误或网络问题解决方案：

验证服务是否运行（使用
```
ps aux
```
、
```
docker ps
```
或类似命令）
确认端口与配置一致（使用
```
netstat -tlnp
```
或
```
ss -tlnp
```
）
检查防火墙规则或容器网络问题

Error: "All Endpoints Timeout"

错误："All Endpoints Timeout"

Cause: Service overwhelmed, wrong host, or proxy misconfiguration Solution:

Test a single endpoint manually with
```
curl -v
```
Increase timeout values in config if service is legitimately slow
Check if a reverse proxy or load balancer is intercepting requests

原因：服务过载、主机错误或代理配置错误解决方案：

使用
```
curl -v
```
手动测试单个端点
如果服务确实较慢，增加配置中的超时时间
检查反向代理或负载均衡器是否拦截了请求

Error: "JSON Parse Failure on expect_key Check"

错误："JSON Parse Failure on expect_key Check"

Cause: Endpoint returns HTML, XML, or empty body instead of JSON Solution:

Verify endpoint actually returns JSON (check Content-Type header)
Remove
```
expect_key
```
if endpoint legitimately returns non-JSON
Check if authentication is required (HTML login page returned)

原因：端点返回HTML、XML或空响应，而非JSON 解决方案：

验证端点是否确实返回JSON（检查Content-Type头）
如果端点确实返回非JSON，移除
```
expect_key
```
配置
检查是否需要认证（可能返回HTML登录页面）

Anti-Patterns

反模式

Anti-Pattern 1: Testing Against Production Without Safeguards

反模式1：无防护地测试生产环境

What it looks like: Pointing base_url at production with POST/DELETE endpoints Why wrong: Can mutate production data, cause outages, or trigger rate limits Do instead: Use staging environments for write operations; production only for GET health checks

表现：将base_url指向生产环境，且包含POST/DELETE端点问题：可能修改生产数据、导致服务中断或触发速率限制 正确做法：在预发布环境测试写操作；生产环境仅用于GET健康检查

Anti-Pattern 2: Ignoring Slow Endpoints

反模式2：忽略慢端点

What it looks like: "All status codes are 200, ship it!" while ignoring 8-second response times Why wrong: Slow endpoints indicate degradation that will become failures under load Do instead: Set

max_time

thresholds and treat SLOW as actionable warnings

表现："所有状态码都是200，可以发布了！"但忽略8秒的响应时间问题：慢端点表明服务性能下降，在负载下会转化为失败 正确做法：设置

max_time

阈值，将SLOW视为可操作的警告

Anti-Pattern 3: Hardcoding Base URLs

反模式3：硬编码基础URL

What it looks like:

"base_url": "http://192.168.1.42:8000"

in checked-in config Why wrong: Breaks on every other machine, CI environment, and deployment target Do instead: Use environment variables or localhost with configurable port

表现：在已提交的配置中写死

"base_url": "http://192.168.1.42:8000"

问题：在其他机器、CI环境或部署目标上会失效 正确做法：使用环境变量或带可配置端口的localhost

Anti-Pattern 4: No Endpoint Config in Repository

反模式4：仓库中无端点配置

What it looks like: Manually listing endpoints every time validation runs Why wrong: Endpoints drift, new ones get missed, no single source of truth Do instead: Maintain

endpoints.json

in version control alongside the API code

表现：每次运行验证时手动列出端点问题：端点会逐渐不一致，新端点被遗漏，缺乏单一可信源 正确做法：在版本控制中维护

endpoints.json

，与API代码放在一起

References

参考资料

This skill uses these shared patterns:

Verification Checklist - Pre-completion checks

本技能使用以下共享模式：

Verification Checklist - 完成前检查

CI/CD Integration

CI/CD集成示例

yaml

undefined

yaml

undefined

GitHub Actions example

GitHub Actions 示例

TODO: scripts/validate_endpoints.py not yet implemented

TODO: scripts/validate_endpoints.py 尚未实现

Manual alternative: use curl to validate endpoints from endpoints.json

手动替代方案：使用curl从endpoints.json验证端点

name: Validate API endpoints run: | jq -r '.endpoints[].path' endpoints.json | while read path; do curl -sf "$BASE_URL$path" > /dev/null && echo "PASS: $path" || echo "FAIL: $path" done


```bash

name: Validate API endpoints run: | jq -r '.endpoints[].path' endpoints.json | while read path; do curl -sf "$BASE_URL$path" > /dev/null && echo "PASS: $path" || echo "FAIL: $path" done


```bash

Pre-deployment gate

部署前关卡

TODO: scripts/validate_endpoints.py not yet implemented

TODO: scripts/validate_endpoints.py 尚未实现

Manual alternative: iterate endpoints.json with curl

手动替代方案：使用curl遍历endpoints.json

jq -r '.endpoints[].path' endpoints.json | while read path; do curl -sf "http://localhost:8000$path" > /dev/null || { echo "FAIL: $path"; exit 1; } done

undefined

jq -r '.endpoints[].path' endpoints.json | while read path; do curl -sf "http://localhost:8000$path" > /dev/null || { echo "FAIL: $path"; exit 1; } done

undefined