一键在 Manus 中运行任何 Skill

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 仓库查看创作者相关仓库

下载

在 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).