원클릭으로 Manus에서 모든 스킬 실행

add-api-route

스타3

포크1

업데이트2026년 5월 1일 22:05

Add a new Axum HTTP route to the vixen-rs server following project conventions for auth, validation, error mapping, and OpenAPI docs. Use when the user asks to add an endpoint, add a route, expose a new API, or extend an existing handler.

설치

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

Manus에서 실행

출처

PlugFox

PlugFox/vixen-rs

GitHub 저장소 열기 Creator 저장소 보기

다운로드

Manus에서 실행

Add API Route (Vixen server)

Read first:

server/docs/rules/api-routes.md — route layout, middleware ordering, request/response shape.
server/docs/rules/error-handling.md — AppError variants, IntoResponse mapping.
server/docs/api.md — the public API reference that MUST be updated.
server/docs/auth.md — when adding routes behind WebApp-initData auth.

File layout

Routes live in server/src/api/routes_*.rs. Add the handler to the matching file; create a new routes_<area>.rs only if the area is genuinely new. Wire it into the router in server/src/api/server.rs.

Checklist

Method + path follow REST conventions. Plural collections (/chats), singular by id (/chats/{chat_id}). Telegram IDs in paths are i64 — declare them as Path<i64>.
Auth: pick the right middleware stack:
- webapp_auth_middleware for moderator dashboard endpoints (validates JWT minted from initData; checks chat_ids claim).
- admin_secret_middleware for ops/admin endpoints (constant-time compare against CONFIG_ADMIN_SECRET).
- No middleware for the public report endpoints (/api/v1/report/{slug}) — those go through pub_rate_limit_middleware.
Extractors in this order: State, path, query, Json body. Typed structs with serde::Deserialize + validation.
Response type: always a concrete serde::Serialize struct, never a raw Value. Use Json<T> or (StatusCode, Json<T>).
Errors: return Result<Json<T>, AppError>. Add new AppError variants in the errors module rather than ad-hoc StatusCode returns.
SQLx queries: use query!/query_as! macros (compile-time checked). Refresh .sqlx/ via /db-migrate or cargo sqlx prepare.
Tracing: #[tracing::instrument(skip(state, body))] — skip large/sensitive args.
OpenAPI: every route needs #[utoipa::path(...)] so the website's typed client stays in sync.

After writing

Update server/docs/api.md with the route, auth requirement, request shape, response shape, error codes.
Add an integration test under server/tests/ that hits the route via axum::Router::oneshot.
Run /server-check.
If the website consumes the route, update website/src/features/{area}/api.ts and types.ts — then /website-check.

Security pitfalls

Authorization ≠ authentication: webapp_auth_middleware only proves the JWT is valid. For chat-scoped endpoints, also check that the requested chat_id is in the JWT's chat_ids claim. Server-side double-check is mandatory — the JWT is just a UI hint.
IDOR via chat_id in path: never trust the path. Re-verify the moderator's access to that chat in every handler.
Rate limits: public endpoints without pub_rate_limit_middleware are a DoS vector.
Bot token / initData in logs: never log raw Authorization headers, never log the JWT body, never include initData in any tracing field above debug level.
Input size: set explicit RequestBodyLimitLayer on any upload-style routes (avatar, custom captcha asset upload if/when added).

이 저장소의 다른 Skills

같은 저장소

bump-version

PlugFox/vixen-rs

Bump the patch version in server/Cargo.toml or website/package.json after completing a major change. Use when the user asks to bump/release a version, or when CLAUDE.md's rule about version bumps after major changes applies.

2026-05-013

change-impact-assessment

PlugFox/vixen-rs

Before a non-trivial change, list affected systems — DB schema, API contract, Telegram handlers, jobs, TS types, docs. Catch ripple effects upfront, not after CI fails. Use when planning a feature, migration, refactor, or any cross-module touch.

2026-05-013

code-review-self

PlugFox/vixen-rs

Self-review before push — read the diff as a reader, scan for vixen footguns (token leaks, PII, idempotency, captcha asset overwrites), run validation pipeline, no surprise files. Use before "git push", before opening a PR, or when the user says "ready to commit".

2026-05-013

commit-message

PlugFox/vixen-rs

Write a git commit message for vixen-rs following the project's Conventional Commits convention. Use when the user asks to commit, create a commit, or write a commit message.

2026-05-013

debug-systematically

PlugFox/vixen-rs

Reproduce → bisect → root cause → fix → verify. Don't speculate, don't "add more error handling" as a guess. Use when something is broken, when a test fails intermittently, when the user says "this isn't working" or "investigate why".

2026-05-013

docker-multi-stage

PlugFox/vixen-rs

Write small, fast, reproducible Dockerfiles for the vixen-rs server (Rust) and website (bun) using multi-stage builds, cache mounts, distroless/alpine runtime images, and non-root users. Use when editing server/Dockerfile, website/Dockerfile, docker-compose.yml, or when the user asks to shrink an image or speed up a Docker build.

2026-05-013

name	add-api-route
description	Add a new Axum HTTP route to the vixen-rs server following project conventions for auth, validation, error mapping, and OpenAPI docs. Use when the user asks to add an endpoint, add a route, expose a new API, or extend an existing handler.

Add API Route (Vixen server)

Read first:

server/docs/rules/api-routes.md — route layout, middleware ordering, request/response shape.
server/docs/rules/error-handling.md — AppError variants, IntoResponse mapping.
server/docs/api.md — the public API reference that MUST be updated.
server/docs/auth.md — when adding routes behind WebApp-initData auth.

File layout

Checklist

Method + path follow REST conventions. Plural collections (/chats), singular by id (/chats/{chat_id}). Telegram IDs in paths are i64 — declare them as Path<i64>.
Auth: pick the right middleware stack:
- webapp_auth_middleware for moderator dashboard endpoints (validates JWT minted from initData; checks chat_ids claim).
- admin_secret_middleware for ops/admin endpoints (constant-time compare against CONFIG_ADMIN_SECRET).
- No middleware for the public report endpoints (/api/v1/report/{slug}) — those go through pub_rate_limit_middleware.
Extractors in this order: State, path, query, Json body. Typed structs with serde::Deserialize + validation.
Response type: always a concrete serde::Serialize struct, never a raw Value. Use Json<T> or (StatusCode, Json<T>).
Errors: return Result<Json<T>, AppError>. Add new AppError variants in the errors module rather than ad-hoc StatusCode returns.
SQLx queries: use query!/query_as! macros (compile-time checked). Refresh .sqlx/ via /db-migrate or cargo sqlx prepare.
Tracing: #[tracing::instrument(skip(state, body))] — skip large/sensitive args.
OpenAPI: every route needs #[utoipa::path(...)] so the website's typed client stays in sync.

After writing

Update server/docs/api.md with the route, auth requirement, request shape, response shape, error codes.
Add an integration test under server/tests/ that hits the route via axum::Router::oneshot.
Run /server-check.
If the website consumes the route, update website/src/features/{area}/api.ts and types.ts — then /website-check.

Security pitfalls

Authorization ≠ authentication: webapp_auth_middleware only proves the JWT is valid. For chat-scoped endpoints, also check that the requested chat_id is in the JWT's chat_ids claim. Server-side double-check is mandatory — the JWT is just a UI hint.
IDOR via chat_id in path: never trust the path. Re-verify the moderator's access to that chat in every handler.
Rate limits: public endpoints without pub_rate_limit_middleware are a DoS vector.
Bot token / initData in logs: never log raw Authorization headers, never log the JWT body, never include initData in any tracing field above debug level.
Input size: set explicit RequestBodyLimitLayer on any upload-style routes (avatar, custom captcha asset upload if/when added).