Agent Skills
› AjayIrkal23/agentic-mercy-10x
› backend-api-standards
backend-api-standards
GitHub规范后端列表与搜索接口的过滤、排序、分页及响应结构。强制DB层处理查询，确保参数白名单验证与稳定格式，禁止内存操作大数据集，指导控制器与服务层职责划分及目录结构。
Trigger Scenarios
添加或修改列表端点
定义查询参数或排序白名单
标准化后端驱动的表格或搜索行为
审查数据库层面的过滤、排序或搜索逻辑
确定分页默认值与边界限制
Install
npx skills add AjayIrkal23/agentic-mercy-10x --skill backend-api-standards -g -y
SKILL.md
Frontmatter
{
"name": "backend-api-standards",
"schema": 1,
"category": "backend",
"surfaces": [
"backend"
],
"triggers": {
"paths": [],
"intents": [
"backend"
],
"keywords": [
"api",
"backend",
"endpoint",
"filtering",
"list",
"needs",
"pagination",
"query",
"response",
"rules",
"search",
"shapes",
"sorting",
"stable",
"standards",
"strict",
"task",
"validation"
]
},
"platforms": [
"linux",
"darwin",
"windows"
],
"token-cost": 962,
"description": "ALWAYS invoke when a backend task needs strict list or search endpoint rules for filtering, sorting, pagination, stable response shapes, or query validation.",
"disable-model-invocation": false
}
Backend API Standards
Overview
This skill owns strict backend list and search endpoint behavior.
Use it when filtering, sorting, pagination, stable list response shapes, thin controllers, or end-to-end query validation must be enforced. For general backend work, start with backend-standards-always-follow.
Use When
- Adding or modifying list endpoints.
- Defining supported query params or sort whitelists.
- Standardizing backend-driven table or search behavior.
- Reviewing DB-level filtering, sorting, or search behavior.
- Locking pagination defaults and bounds.
Do Not Use
- Envelope design by itself.
- Controller/service boundaries by themselves.
- Error taxonomy by itself.
Core Rules
- Table and list endpoints must support backend-side pagination, filtering, and sorting.
- List responses must stay stable across domains.
- Filtering, sorting, and search must run in the DB layer, not in memory for real datasets.
- Query, body, and params input must be validated with schemas.
- Query params must be sanitized, normalized, type-cast, and whitelisted.
- Unknown filters are rejected by default unless explicitly allowed.
- Sort keys must be whitelisted.
- Controllers stay thin: validate, call service, return response.
- Services own query building, pagination, sort whitelists, and overflow handling.
Default Query Behavior
{
"page": 1,
"limit": 20,
"sortBy": "createdAt",
"sortOrder": "desc"
}
Recommended maximum:
maxLimit = 100
Stable List Response
{
"items": [],
"page": 1,
"limit": 20,
"total": 0,
"totalPages": 0,
"sortBy": "createdAt",
"sortOrder": "desc"
}
Endpoint Expectations
List endpoints should typically support:
pagelimitsortBysortOrderqwhen search is supported- explicit domain filters
Preferred Structure
- Root route registry in
/routes/index.ts - Domain route registry in
/routes/{domain}/index.ts - Leaf route in
/routes/{domain}/{action}.route.ts - Root controller registry in
/controllers/index.ts - Domain controller registry in
/controllers/{domain}/index.ts - Leaf controller in
/controllers/{domain}/{action}.controller.tsor repo-local feature folders like/controllers/{domain}/{feature}/{action}.controller.ts - Schema in
/schemas/{domain}/{action}.schema.tsor repo-local feature folders like/schemas/{domain}/{feature}/{action}.schema.ts - Types in
/types/{domain}/{name}.ts - Service in
/services/{domain}/{action}.service.tsfor flat repos, or/services/{domain}/{feature}/index.tswith action entry files and helper modules when the repo uses controller-mirror feature folders - Query helpers in
/utils/{domain}/query.ts
Safety Rules
- No fetch-all-then-filter for large datasets.
- No unbounded list responses.
- No in-memory sort for large result sets.
- No silent acceptance of unknown query keys.
Performance Notes
- Check indexes for new filter or sort paths.
- Call out regex or search risks on large collections.
- Treat repeated list access as a performance-sensitive surface.
- Preserve response keys and query param names while optimizing.
- Treat manually maintained backend source files above 250 lines as a structural violation for touched API surfaces; split routes, schemas, controllers, services, query helpers, or mappers before adding more behavior unless the user explicitly scopes that cleanup out.
Combine With
backend-standards-always-followfor the default backend baseline.service-layer-standardsfor thin-controller execution.api-contract-standardsfor response envelope rules.backend-performance-standardswhen scale, repeated DB work, or hot-path efficiency is the main concern.
References
- Use
references/full-guide.mdfor the longer strict version and implementation details.
Version History
- 581d130 Current 2026-07-19 09:04
