controller

A controller development rule for Spring-style web APIs. It defines URL naming, allowed HTTP methods, annotations, method order, and how controllers call services.

In plain words
What is it for?
Use it when creating or reviewing controllers, routes, GET and POST endpoints, annotations, and controller-to-service calls.
Why use it?
It gives API endpoints a predictable structure, making them easier to use, review, and maintain.

Cursor rule for Cursor

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add rules/sunmh207/entire-dashboard/controller
Clone the repo
git clone --depth 1 https://github.com/sunmh207/entire-dashboard

Made for: Cursor.

Per session 0 Nothing until a file matches its globs; then the whole rule loads.
When invoked 770 The whole file, excluding the scripts and references it only reads on demand.
Security scan A 0 findings. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00000 $0.00770
Opus 5 $0.00000 $0.00385
Sonnet 5 $0.00000 $0.00154
Haiku 4.5 $0.00000 $0.00077

Measured yesterday against content hash c361b9cd6122, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade A, and why

controller scanned grade A with 0 findings against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Nothing flagged

None of the 26 patterns this scan looks for appear in this file: no shell pipes, no recursive deletes, no credential paths, no hidden text, no instruction-override or anti-refusal phrasing, no agent-config snooping. That is not a guarantee, it is the absence of the things that are checkable.

server/.cursor/rules/controller.mdc · 77 lines

What it actually says

Controller 开发规范

1. URL 命名

采用 /{service}/{method} 的命名方式,命名使用小写字母,多个单词之间使用 "-" 隔开。

示例:

  • 创建项目: /repo/create
  • 删除项目: /repo/delete
  • 获取一个项目: /repo/get
  • 根据 ID 列表列出项目:/repo/list-by-ids
  • 根据动态条件查询项目:/repo/search

补充说明:

  • 方法名必须使用动词短语,表示动作,如:create, delete, update-status, reset-password
  • 列表查询统一用:
    • list:无筛选条件,例如 /repo/list
    • list-by-ids:根据 ID 集合,例如/repo/list-by-ids
  • 搜索类接口统一使用:search:带条件的分页/列表查询,例如 /repo/search
  • URL 中不要出现与 HTTP 动词重复的词,如 /repo/get-repo(bad)。
  • URL 统一以服务名开头,例如 /repo/...

2. HTTP 动词

仅使用GETPOST这两个 HTTP 动词。

  • GET: 用在查询类接口,不对数据变更;
  • POST: 用在新增、修改、删除、执行动作(有状态变更)。

3. Controller 类注解

按以下顺序添加注解:

  • (1). 组件 / 身份类(我是谁): @RestController
  • (2). 构造器 / 注入类(我怎么被创建):@RequiredArgsConstructor,且依赖的成员变量需添加 final;禁止使用 @AllArgsConstructor
  • (3). 日志 / 技术辅助类(我有哪些能力):@Slf4j...
  • (4). 路由 / 接口语义(我对外暴露什么):@RequestMapping
  • (5). 文档 / 描述 / 排序类(我在文档中长什么样):@Tag@ApiOrder

4. Controller 代码结构与方法顺序

Controller 的方法顺序必须与对应 Service 中的方法顺序保持一致,即业务操作在前,查询类方法在后,这样有利于:

  • 便于查阅与维护;
  • 保持模块内逻辑结构一致;
  • 减轻代码 review 负担;

5. Controller 与 Service 的调用关系规范

  • Controller 中的 {service}/get 类型的接口,调用对应 Service 的 get 接口。

6. 异常与错误码规范

  • Controller 不处理业务异常,统一由全局异常处理器转换为标准 API 错误响应。

7. 风格与规范性要求

Controller 必须保持 瘦逻辑:

  • 不做复杂业务
  • 不做拼装或转换逻辑(使用 Mapper)
  • 不做条件判断业务(交给 Service)

8. Swagger 注解规范

  • Controller 类需添加 @Tag 注解,用于标识 Controller 的名称和描述。
  • Controller 方法需添加 @Operation 注解,用于标识方法的名称和描述。
  • Controller 方法参数需添加 @Parameter 注解,用于标识参数的名称和描述。
  • Controller 类、以及方法需添加 @ApiOrder 注解,用于标识方法的顺序。
Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. yesterday First seen · 77 lines · 770 tokens per session scan A c361b9cd6122

Subscribe to this mod's changes

controller is a cursor rule published in the GitHub repository sunmh207/entire-dashboard (24 stars, last pushed 2mo ago), licensed MIT. It costs nothing until one of its globs matches a file; then it loads 770 tokens. A static security scan graded it A with 0 findings. No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.