✨ feat(vscode): 代码阅读的 FastAPI 路由器单独一张「路由器」卡片(前缀、标签、依赖、默认响应,接口表列挂在它上面的接口,函数名 ⌘ + 点击跳到接口卡片);接口卡片写所属路由器

This commit is contained in:
cruldra committed 2026-09-27 21:26:36 +08:00
1 parent b4e4879570
commit 71641bdc41
6 files changed
+278 -26

No files matched your search

+42 -7
View File
@@ -126,9 +126,9 @@
| enum 枚举 | `list-ordered` | else 否则 | `corner-down-right` | statement 语句 | `code` |
| exception 异常 | `triangle-alert` | loop 循环 | `repeat` | comment 注释 | `message-square-text` |
库规则的种类用规则给的图标(`KindBadge.icon`):SQLAlchemy 数据表 `database`、数据类 `package`、Celery 应用 `server-cog`、定时任务 `calendar-clock`、FastAPI 接口 `globe`。
库规则的种类用规则给的图标(`KindBadge.icon`):SQLAlchemy 数据表 `database`、数据类 `package`、Celery 应用 `server-cog`、定时任务 `calendar-clock`、FastAPI 接口 `globe`、FastAPI 路由器 `network`。
这组图标由插件自己定义,是一个封闭的集合:契约里的 `KIND_ICON_NAMES`(上表 18 个加库规则用的 5 个,lucide 的 kebab-case 名字),类型 `KindIconName` 是它们的联合,`KindBadge.icon` 只能写其中一个,写别的是类型错误。webview 给每个名字配一个逐个 import 的 lucide 图标组件(`kindIcons.tsx` 的 `KIND_ICON_COMPONENTS`,打包只带这些,预览脚本约 157 kB);webview 的 `KindIconName` 照契约手抄,`kindIconNames.test.ts` 核对两边一样。规则要新图标就把名字加进这组、在 webview 配上图标,没有按任意名字找图标的路。
这组图标由插件自己定义,是一个封闭的集合:契约里的 `KIND_ICON_NAMES`(上表 18 个加库规则用的 6 个,lucide 的 kebab-case 名字),类型 `KindIconName` 是它们的联合,`KindBadge.icon` 只能写其中一个,写别的是类型错误。webview 给每个名字配一个逐个 import 的 lucide 图标组件(`kindIcons.tsx` 的 `KIND_ICON_COMPONENTS`,打包只带这些,预览脚本约 157 kB);webview 的 `KindIconName` 照契约手抄,`kindIconNames.test.ts` 核对两边一样。规则要新图标就把名字加进这组、在 webview 配上图标,没有按任意名字找图标的路。
- 右上角的图标按钮(原型组件 `Reader / BlockTools`,普通块、属性表块、库规则的卡片共用):只有图标、不带字,名字写在悬停提示和 `aria-label` 里;整排是 `role="group"`(`aria-label="块操作"`)。先是「问 AI」(sparkles 图标,点开 / 收起块下面的问答区,展开时带按下的底色、`aria-expanded`;文件不在工作区文件夹里时没有,见「问 AI」),再是「编辑 / 预览」切换:预览时铅笔「编辑」,编辑时眼睛「预览」、带按下的底色(`--vscode-toolbar-activeBackground`)。按钮宽 24px、高 20px(和种类图标同高),图标 14px、`descriptionForeground` 色;悬停 `--vscode-toolbar-hoverBackground`,键盘聚焦描 1px `--vscode-focusBorder`;Tab 能走到,回车 / 空格切换。
- 悬停提示(整个预览只走这一条路,看板 webview 共用同一个组件):带提示的元素只写 `data-tooltip="提示"`(名字照旧写在 `aria-label` 里),页面根上挂一个 `TooltipHost`(`webview-ui/src/components/ui/tooltip.tsx`)统一弹,不用原生 `title`。原因:macOS 上 VS Code 带的 Electron(1.139 是 Electron 43)只在鼠标压着带 `title` 的元素自身边缘时才弹原生提示,停在它里面的图标、文字上不弹(electron/electron#49843,Electron 38 起),种类图标 20px 的框几乎被 16px 的图形占满,基本弹不出来;样子也是系统的。样子照 VS Code 的悬停框:`--vscode-editorHoverWidget-background` 底、`--vscode-editorHoverWidget-border` 边框、`--vscode-editorHoverWidget-foreground` 字、`0 2px 8px --vscode-widget-shadow` 阴影,11px 字,圆角 4px,最宽 22rem;优先在元素上方,上方放不下翻到下方,水平对着元素中间,贴边留 8px,不接鼠标。鼠标停 500ms 才弹,在同一个元素里移动不重新计时,已经弹着时移到另一个带提示的元素上立刻换;移开、移出页面、按下鼠标、按任意键(含 Esc)、滚动就收,收了之后鼠标不离开这个元素不再弹。键盘把焦点移到带提示的元素上(`:focus-visible`)立刻弹,焦点离开就收;提示不是元素自己的名字(`aria-label` 或它的字)时用 `aria-describedby` 挂到元素上,读屏当描述念。
- 种类图标和底色按种类区分(颜色见「颜色」);注释块虚线框。
@@ -669,7 +669,7 @@ export interface Translator {
export interface ThemeColor { dark: string, light: string }
/** 种类图标:插件自己定义的一组 lucide 图标(kebab-case 名字);前 18 个给内置种类,后面的给库规则。规则要新图标就加进这组,没有按任意名字找图标的路。 */
export const KIND_ICON_NAMES = ['import', 'square-function', /* …18 个内置种类的… */ 'database', 'package', 'server-cog', 'calendar-clock', 'globe'] as const
export const KIND_ICON_NAMES = ['import', 'square-function', /* …18 个内置种类的… */ 'database', 'package', 'server-cog', 'calendar-clock', 'globe', 'network'] as const
export type KindIconName = (typeof KIND_ICON_NAMES)[number]
/** 库规则的种类:块左边只画图标(种类色),label 是悬停提示和读屏念的名字,筛选栏里也叫它;icon 只能从 KindIconName 里挑。 */
@@ -1022,7 +1022,40 @@ export interface CodeReaderApi {
### 内置:FastAPI 接口(Python)
`vscode/src/codeReader/rules/fastapi.ts`,`libraries: ['fastapi']`。原型:`code.js` 的「库规则:FastAPI 接口」一节(`ROUTE_SAMPLE`、`routeCard`),画板「库规则 · FastAPI 接口」;样例是 luffy 的 `user/routes.py`(`fixtures/routes.py`)、`skill_hub/routes.py`(`fixtures/skillHubRoutes.py`)、`user/console/routes.py`(节选在 `fixtures/consoleRoutes.py`)。种类 `fastapi.route`,名字「接口」,图标 `globe`,颜色暗 #61afef / 亮 #1a6fb5,和函数块一样默认收起子块。
`vscode/src/codeReader/rules/fastapi.ts`,`libraries: ['fastapi']`。原型:`code.js` 的「库规则:FastAPI 接口」一节(`ROUTER_SAMPLE`、`routerCard`、`ROUTE_SAMPLE`、`routeCard`),画板「库规则 · FastAPI 接口」;样例是 luffy 的 `user/routes.py`(`fixtures/routes.py`)、`skill_hub/routes.py`(`fixtures/skillHubRoutes.py`)、`user/console/routes.py`(节选在 `fixtures/consoleRoutes.py`)。路由器和挂在它上面的接口是两回事,各一张卡片:
- 接口:种类 `fastapi.route`,名字「接口」,图标 `globe`,颜色暗 #61afef / 亮 #1a6fb5,和函数块一样默认收起子块。见下面「接口卡片」。
- 路由器:种类 `fastapi.router`,名字「路由器」,图标 `network`,颜色暗 #7aa2f7 / 亮 #34548a(Tokyo Night 的蓝,亮色取它 Day 主题的)。见下面「路由器卡片」。
#### 路由器卡片
模块顶层 `X = APIRouter(...)` / `X = FastAPI(...)` 的赋值(常量、变量块,只声明它一个)整块换成「路由器」卡片,没有子块可并。属性表(有才显示):
| 行 | 内容 |
| --- | --- |
| 名称 | 赋值目标(variable 色,带下标;跳到路由器的定义闪整张卡片) |
| 说明 | 赋值后面的属性 docstring;Markdown |
| 前缀 | `prefix=`,着色同接口卡片的 URL;`FastAPI(...)` 没有 |
| 标签 | `tags=`,同接口卡片 |
| 依赖 | `dependencies=[Depends(x)]` 写 `x`,写了才有 |
| 默认响应 | `responses={...}`,写了才有;值和表格同接口卡片的「响应」 |
| 接口 | `N 个`(hint),下面一张表格「方法 \| 路径 \| 函数 \| 说明」,列这份文件模块顶层挂在它上面的全部接口,照源码顺序;一个都没有时写「0 个」、不画表格 |
接口表的格子:方法同接口卡片(Swagger UI 的颜色);路径是完整的(前缀 + 装饰器里的路径),着色同接口卡片的 URL,`{参数}` 里的名字讲的是那个函数的同名参数(`refers`);函数是函数名(function 色,带下标:⌘ + 点击跳到它的定义,就是那张接口卡片,闪整张卡片);说明是函数 docstring 的第一行(comment 色),没有 docstring 留空。
样例(`fixtures/routes.py` 的 `router`,测试里逐字核对):
```
名称: router
前缀: /users
标签: 用户管理
接口: 3 个
GET | /users/{user_id} | get_user | 获取用户详情。
PUT | /users/{user_id} | update_user | 更新用户信息。
POST | /users/me/avatar | upload_current_user_avatar | 上传当前登录用户头像。
```
#### 接口卡片
- 认哪些函数:装饰器是 `@<路由对象>.<方法>(...)`,方法是 get / post / put / patch / delete / head / options / trace,路由对象是同一文件模块顶层 `X = APIRouter(...)` / `X = FastAPI(...)` 赋值出来的(`APIRouter`、`FastAPI` 从 fastapi 导入,别名、`fastapi.APIRouter` 也算)。路由对象从别的文件导入的、`@router.get` 不带括号的、`@router.websocket` 不认。几个路由装饰器时取第一个。
- 整个函数块换成卡片,不并子块:函数体照常是子块;编辑范围同别的卡片,是整条语句(连装饰器的整个函数)。
@@ -1035,6 +1068,7 @@ export interface CodeReaderApi {
| --- | --- |
| 名称 | 函数名(function 色,带下标) |
| 说明 | 函数的 docstring,同函数块;Markdown |
| 路由器 | 挂在哪个路由对象上:它的名字(variable 色,带下标,⌘ + 点击跳到路由器卡片) |
| 标签 | 路由对象的 `tags=` 加装饰器的 `tags=`,字符串不带引号(string 色,带下标),「、」隔开 |
| 异步 | 是 / 否(storage 色) |
| 装饰器 | 路由装饰器以外的装饰器(`@cache(60)`),有才显示 |
@@ -1077,6 +1111,7 @@ export interface CodeReaderApi {
```
名称: update_user
说明: 更新用户信息。…
路由器: router
标签: 用户管理
异步: 是
依赖: get_db(db)、get_current_user(current_user)
@@ -1295,7 +1330,7 @@ type BlockView = BlockViewBase & ({ translation: PreviewText, doc?: Markdown } |
带自己颜色的段(`Segment.color`,库规则按库的配色给,例如 FastAPI 的 HTTP 方法、成功的状态码):暗色、亮色两个写在元素的 style 上(`--color-dark` / `--color-light`),`.cr-colored` 按主题挑一个,盖过词性的颜色;词性照旧报(`role`)。
种类(种类图标的颜色 + 块底 7% + 边框 35%;亮色主题同色系;图标见「预览(代码块树)」):import 导入 #c586c0;function 函数 #dcdcaa;class 类、type 类型 #4ec9b0;enum 枚举 #b180d7(亮色 #652d90);exception 异常 #f14c4c(亮色 #cd3131,和尝试、捕获、最终同一色系,更红一些);field 字段、const 常量、variable 变量 #9cdcfe;if 条件、else 否则 #ce9178;loop 循环 #8f9cff;try 尝试、catch 捕获、finally 最终 #f48771;return 返回 #89d185;statement 语句 #9d9d9d;comment 注释 #6a9955(虚线框);库规则的种类用规则给的颜色(`badge.color` 的 dark / light,webview 写在块的 style 上按主题挑),内置 SQLAlchemy 数据表 #e8a860 / #a3590d,Celery 应用 #98c379 / #4d7f17,定时任务 #56b6c2 / #127f8c,数据类 #ef7fb0 / #b3306c,FastAPI 接口 #61afef / #1a6fb5。编辑状态:底色 `--vscode-editor-background`,边框 `--vscode-focusBorder`。
种类(种类图标的颜色 + 块底 7% + 边框 35%;亮色主题同色系;图标见「预览(代码块树)」):import 导入 #c586c0;function 函数 #dcdcaa;class 类、type 类型 #4ec9b0;enum 枚举 #b180d7(亮色 #652d90);exception 异常 #f14c4c(亮色 #cd3131,和尝试、捕获、最终同一色系,更红一些);field 字段、const 常量、variable 变量 #9cdcfe;if 条件、else 否则 #ce9178;loop 循环 #8f9cff;try 尝试、catch 捕获、finally 最终 #f48771;return 返回 #89d185;statement 语句 #9d9d9d;comment 注释 #6a9955(虚线框);库规则的种类用规则给的颜色(`badge.color` 的 dark / light,webview 写在块的 style 上按主题挑),内置 SQLAlchemy 数据表 #e8a860 / #a3590d,Celery 应用 #98c379 / #4d7f17,定时任务 #56b6c2 / #127f8c,数据类 #ef7fb0 / #b3306c,FastAPI 接口 #61afef / #1a6fb5,FastAPI 路由器 #7aa2f7 / #34548a。编辑状态:底色 `--vscode-editor-background`,边框 `--vscode-focusBorder`。
## 代码位置
@@ -1315,7 +1350,7 @@ vscode/src/codeReader/
rules/celery.ts 内置 Celery 库规则:两张卡片、频率换算、任务名索引
rules/enum.ts 内置 enum 库规则(Python):枚举类认成枚举块,成员照 Python 的规则认
rules/dataclass.ts 内置 dataclasses 库规则(Python):数据类卡片,字段照 dataclasses 的规则认
rules/fastapi.ts 内置 FastAPI 库规则(Python):接口卡片(请求表、响应表),参数照 FastAPI 的规则放,异常类的状态码、类型别名、枚举经索引查
rules/fastapi.ts 内置 FastAPI 库规则(Python):路由器卡片(接口表)、接口卡片(请求表、响应表),参数照 FastAPI 的规则放,异常类的状态码、类型别名、枚举经索引查
ruleLookups.ts 库规则认领时查别的文件里的定义(RuleContext.lookup):先交出已知的、记下问了什么,发出预览后查(索引 + 语言扩展查定义),变了叫宿主重发(不碰 VS Code)
rules/pythonTree.ts Python 库规则共用的读语法树的办法(名字最后一节、字符串内容、调用的参数、别名、注解里的 X[...]、库里的名字)
rules/segments.ts 库规则共用的拼属性表文字的办法
@@ -1402,7 +1437,7 @@ vscode/webview-ui/code-reader.html + src/codeReader/ 预览界面(React,Vit
- Celery 规则:`fixtures/celeryApp.py` 的应用卡片和定时任务卡片逐字同上面的样例(列名、「12 条,另有展开 1 处」、行尾注释、条目里单独成行的注释、跨行的 `10⏎ * 60`、`每 get_settings().… 秒`、展开一行);任务名是引用、下标指回源码原文;应用卡片的位置参数按参数顺序认、别的参数各一行、展开、属性 docstring、别名;没导入 celery、不是 `Celery(...)` 的不认;频率换算(秒数算式、`timedelta`、`crontab` 各种写法、`schedule`、换算不了的「每 X 秒」和照写法);说明取哪些注释;条目名和任务名不同、没写任务名、任务名不是字符串、值不是字典、选项一列有才有;`conf.update(beat_schedule=…)`、不带 `beat_schedule` 的 `conf.update` 和 `autodiscover_tasks` 照常。任务名索引:显式 `name=`、默认「模块路径.函数名」(包、`src` 下的命名空间包、没有包)、`@shared_task` / `@shared_task()` / `@app.task` 不带括号 / 老写法 `@task`、`async def`、函数里的只认显式名字、`name=` 不是字符串的不认、同名几处都给、文件改了和新建 `__init__.py` 后跟着变、没有任务装饰器的文件不解析。
- 枚举(`rules/enum.test.ts`、`languages/typescript.test.ts`):`fixtures/enumModels.py` 的 `CommissionStatus` 逐字同上面的样例,`SecretScope` 的 docstring 当说明、没有说明列;种类 enum、叫「枚举」、访问级别同原来的类、没有标签(badge),编辑范围是整个类;Python 成员规则(dunder、sunder、私有名、`_ignore_`、lambda、`property`、`nonmember`、只写注解的不是成员,`auto()` 写「自动」,`member(x)` 取 x,说明取上面的注释块、行尾注释、属性 docstring,装饰器);方法、嵌套类、不是成员的属性照源码顺序是子块,成员前面的注释并进来、最后面的留下,「编辑」写回整个类;类名、成员名的定义范围和带下标的词指回源码原文;没导入 enum、SQLAlchemy 的 `Enum`、不是枚举类型的父类不认,`import enum as e` 的 `e.IntEnum` 认。TypeScript:`enums.ts` 里 export / const / declare / 函数里的 enum 都是枚举块、JSDoc 进头部,写的值、自增算出的值(接不上数字就没有)、说明(上面的注释和 JSDoc、行尾注释,同一行的 JSDoc 讲下一个),访问级别;自增的值和「自动」按 hint。TypeScript 和 Python 同样的成员得到一样的种类、属性表行、列名和格子着色(除了 Python 多的「继承」)。宿主:规则认成现成属性表块时照语言插件报的这种块显示、并进来的不是子块时照常显示;webview 枚举块默认折叠。
- 数据类(`rules/dataclass.test.ts`):`fixtures/dataclassModels.py` 的 `SandboxAccess` 逐字同上面的样例,`AdminUserRow`、`RedirectPayResult`(`field(init=False, default=…)`)、`SmsSent`(`default_factory=dict`)的行;种类 `dataclasses.dataclass`、叫「数据类」、颜色、访问级别同原来的类;编辑范围是整个类、写回原样,`__post_init__` 是子块;类名、字段名的定义范围和带下标的词指回源码原文;装饰器的写法(别名、`dataclasses.dataclass`、`dc.dataclass`)认,pydantic 的、`other.dataclass` 不认,没导入 dataclasses 不认;每个选项的译法、默认值不讲、别的照写、`**x`、别的装饰器一行;字段规则(`ClassVar`、`typing.ClassVar` 留作子块,`InitVar` 的类型和「仅初始化时使用」,`KW_ONLY` 记号并进来、后面的字段「只能按名字传参」、单独写 `kw_only=False` 的「可按位置传参」),`field(...)` 的默认值、`default_factory`(名字、lambda)、各参数、`metadata` 照写、`doc=`,说明取上面的注释块、行尾注释、属性 docstring;没注解的类属性、字段中间的方法照源码顺序是子块,「编辑」写回整个类。
- FastAPI 接口(`rules/fastapi.test.ts`):`fixtures/routes.py` 的 `update_user` 逐字同上面的样例(查到 `Forbidden` 是 403 时四条消息写在一行,没查到时不列),名字、颜色、图标、列名、筛选属性、定义范围、编辑范围是整个函数、函数体是子块;着色(URL 的 `{参数}` / 路径,花括号里的参数名 `refers` 到函数的参数,方法的 Swagger 颜色、成功的状态码绿色、自动带的 422 淡色,带下标的词指回源码原文);`fixtures/skillHubRoutes.py` 的 `list_skills`(Annotated 里的 Query、`_` 的依赖)、`get_skill`(HTTPException 的 status_code / detail)、`install`(Request 不算、`-> None` 没有内容);`fixtures/consoleRoutes.py` 的 `create_user`(`status_code=201`、Pydantic 模型、调别的函数间接抛的不算)、`list_users`(查到的类型别名 `FilterQuery` 是依赖、Literal 是简单类型);参数放在哪儿的各条(路径里的名字含 `{x:path}`、各种标记两种写法、上传文件、枚举和类型别名查到的、Pydantic 模型、`Security`、`Depends()`);标签、依赖、`responses=` 叠上路由对象的,`status.HTTP_…` 常量、`response_model=None`、`response_description`、`raise … from`、只写 `raise`、嵌套函数里的;`FastAPI()` 上的接口、别的装饰器一行;不认的(没导入、路由对象在别的文件、不是路由对象、`websocket`、不带括号)。跨文件(工作区索引 + 假的语言扩展):`update_user` 的 `Forbidden` 按定义处查到 `core/exceptions/schemas.py` 的 403,同名的别处的类不算;索引认的类上的 `status_code`(带注解、常量)、枚举类、`Annotated` 类型别名,普通类不认。
- FastAPI 接口(`rules/fastapi.test.ts`):`fixtures/routes.py` 的 `update_user` 逐字同上面的样例(查到 `Forbidden` 是 403 时四条消息写在一行,没查到时不列),名字、颜色、图标、列名、筛选属性、定义范围、编辑范围是整个函数、函数体是子块;着色(URL 的 `{参数}` / 路径,花括号里的参数名 `refers` 到函数的参数,方法的 Swagger 颜色、成功的状态码绿色、自动带的 422 淡色,带下标的词指回源码原文);`fixtures/skillHubRoutes.py` 的 `list_skills`(Annotated 里的 Query、`_` 的依赖)、`get_skill`(HTTPException 的 status_code / detail)、`install`(Request 不算、`-> None` 没有内容);`fixtures/consoleRoutes.py` 的 `create_user`(`status_code=201`、Pydantic 模型、调别的函数间接抛的不算)、`list_users`(查到的类型别名 `FilterQuery` 是依赖、Literal 是简单类型);参数放在哪儿的各条(路径里的名字含 `{x:path}`、各种标记两种写法、上传文件、枚举和类型别名查到的、Pydantic 模型、`Security`、`Depends()`);标签、依赖、`responses=` 叠上路由对象的,`status.HTTP_…` 常量、`response_model=None`、`response_description`、`raise … from`、只写 `raise`、嵌套函数里的;`FastAPI()` 上的接口、别的装饰器一行;不认的(没导入、路由对象在别的文件、不是路由对象、`websocket`、不带括号)。跨文件(工作区索引 + 假的语言扩展):`update_user` 的 `Forbidden` 按定义处查到 `core/exceptions/schemas.py` 的 403,同名的别处的类不算;索引认的类上的 `status_code`(带注解、常量)、枚举类、`Annotated` 类型别名,普通类不认。路由器卡片:`fixtures/routes.py` 的 `router` 逐字同上面的样例,名字、颜色、图标、列名、编辑范围、定义范围;接口表的函数名带下标、路径里的 `{user_id}` 各 `refers` 到各自函数的参数、方法的颜色;接口卡片的「路由器」行排在说明后面、名字带下标指回路由器;写了依赖、默认响应才有这两行,`FastAPI()` 没有前缀,属性 docstring 是说明,没挂接口时「0 个」、不画表格。
- 规则查别的文件里的定义(`ruleLookups.test.ts`):第一遍当没查到、记下问了什么(同一索引同名的只记一处);查到后叫重排,交出定义处正是的那一项;同一版本不再查;索引里没有同名的不问语言扩展,定义处不是索引里的项算没有,没变不叫重排;新版本先用上一版的、再查、变了才叫重排;语言扩展没答时已知的不动、隔一会儿再查。
- 带自己颜色的词(webview `SegmentText.test.tsx`):`cr-colored`,暗色、亮色写在 style 上;讲别处名字的段 `data-offset` 记那个名字的下标。
- 异常(`languages/exceptions.test.ts`,真实解析 + 中文直译 + 视图数据):`fixtures/appExceptions.py` 的 `AppException`、`NotFound` 逐字同「异常」的样例(列名随有没有类型、说明变),`GatewayTimeout` 的多段说明,方法是子块;`fixtures/commerceExceptions.py` 16 个类都是异常、只有说明的四行、写了 `__init__` 的构造参数;认哪些类(自带的异常类、`Warning`、不合后缀的自带类 `StopIteration` / `KeyboardInterrupt`、`pkg.errors.AppException`、同一文件里写在后面的父类一层层往下传、泛型和别的父类混写,关键字参数、`Mapping[...]`、`*bases` 不算,函数里的类也认);类属性(带不带注解、只写注解、说明取上面的注释块 / 行尾注释 / 属性 docstring,连着赋值、解构赋值、方法、讲方法的注释、最后面的注释留作子块),构造参数去掉 self、`*args` 开头的不去;`@dataclass` 的异常类照样是异常卡片;编辑范围是整个类、改卡片写回整个类,类名、属性名、参数名的定义范围和带下标的词指回源码原文;TypeScript `fixtures/exceptions.ts.txt`(`extends Error`、类字段含 static、参数属性、JSDoc、写在后面的父类、类表达式、`ns.X<T>`,父类名不合习惯的照常是类)、JavaScript 的类字段;TypeScript 和 Python 同样的异常得到一样的行和列名;筛选的种类叫「异常」、没有 badge;属性的中文名和去掉行尾记号。webview:异常块默认折叠(`viewState.test.ts`),跳到类名闪整块、属性名 / 构造参数名只闪表里那一行(`reveal.test.ts`)。
+1
View File
@@ -444,6 +444,7 @@ export const KIND_ICON_NAMES = [
'server-cog',
'calendar-clock',
'globe',
'network',
] as const
export type KindIconName = (typeof KIND_ICON_NAMES)[number]
+85 -2
View File
@@ -69,6 +69,7 @@ describe('fastapi 库规则:接口卡片', () => {
expect(propertyLines(properties(card))).toEqual([
'名称: update_user',
'说明: 更新用户信息。\n\n管理员可更新任意用户,普通用户只能更新自己的基础资料。',
'路由器: router',
'标签: 用户管理',
'异步: 是',
'依赖: get_db(db)、get_current_user(current_user)',
@@ -82,7 +83,7 @@ describe('fastapi 库规则:接口卡片', () => {
' 403 | Forbidden | 无权更新此用户信息;无权修改角色;无权修改启用状态;无权修改密码',
' 422 | 参数校验失败 | FastAPI 自动返回',
])
expect(properties(card).map(row => row.columns)).toEqual([undefined, undefined, undefined, undefined, undefined, ['项', '值'], ['状态码', '内容', '说明']])
expect(properties(card).map(row => row.columns)).toEqual([undefined, undefined, undefined, undefined, undefined, undefined, ['项', '值'], ['状态码', '内容', '说明']])
expect(card.attributes).toMatchObject({ kind: 'fastapi.route', access: 'public', async: 'true', httpMethod: 'PUT' })
expect(fastapiRule.attributeNames?.('zh')).toEqual({ attributes: { httpMethod: '请求方法' }, values: {} })
expect(ROUTES.slice(card.defines?.startIndex, card.defines?.endIndex)).toBe('update_user')
@@ -123,6 +124,7 @@ describe('fastapi 库规则:接口卡片', () => {
it('luffy 的 list_skills:Annotated 里的 Query 是查询参数(类型取 Annotated 的第一项),Depends 是依赖,参数名是 _ 的只写依赖', async () => {
expect(propertyLines(properties(await route(SKILL_HUB, 'list_skills')))).toEqual([
'名称: list_skills',
'路由器: skill_hub_router',
'标签: skill-hub',
'异步: 是',
'依赖: get_db(db)、get_current_user',
@@ -142,7 +144,7 @@ describe('fastapi 库规则:接口卡片', () => {
' 404 | HTTPException | f"技能不存在: {slug}"',
' 422 | 参数校验失败 | FastAPI 自动返回',
])
expect(propertyLines(properties(await route(SKILL_HUB, 'install'))).slice(4)).toEqual([
expect(propertyLines(properties(await route(SKILL_HUB, 'install'))).slice(5)).toEqual([
'请求: POST /skill-hub/apps/{app_id}/skills/{slug}',
' URL | /skill-hub/apps/{app_id}/skills/{slug}',
' 方法 | POST',
@@ -157,6 +159,7 @@ describe('fastapi 库规则:接口卡片', () => {
expect(propertyLines(properties(await route(CONSOLE, 'create_user', known({ Forbidden: '403' }))))).toEqual([
'名称: create_user',
'说明: 创建新用户。\n\n需要管理员权限。密码会自动哈希。',
'路由器: router',
'标签: 用户管理-运维',
'异步: 是',
'依赖: get_db(db)、require_users_create',
@@ -239,6 +242,7 @@ def remove(item_id: int):
expect(propertyLines(properties(await route(source, 'remove')))).toEqual([
'名称: remove',
'说明: 删掉一个物品。',
'路由器: router',
'标签: 物品、管理',
'异步: 否',
'依赖: verify_token、audit',
@@ -265,6 +269,7 @@ async def health() -> dict:
`
expect(propertyLines(properties(await route(source, 'health')))).toEqual([
'名称: health',
'路由器: app',
'异步: 是',
'装饰器: @cache(60)',
'请求: GET /health',
@@ -303,6 +308,84 @@ def e():
})
})
/** 名字是 name 的路由器卡片。 */
async function routerCard(source: string, name: string): Promise<BlockView> {
const found = flatten(await views(source)).find(view => view.kind === 'fastapi.router' && view.defines && source.slice(view.defines.startIndex, view.defines.endIndex) === name)
if (!found)
throw new Error(`没有 ${name} 的路由器卡片`)
return found
}
describe('fastapi 库规则:路由器卡片', () => {
it('luffy 的 router:名称 / 前缀 / 标签,接口表列这份文件里挂在它上面的接口(方法 / 完整路径 / 函数 / docstring 第一行)', async () => {
const card = await routerCard(ROUTES, 'router')
expect(card.badge).toEqual({ label: '路由器', color: { dark: '#7aa2f7', light: '#34548a' }, icon: 'network' })
expect(propertyLines(properties(card))).toEqual([
'名称: router',
'前缀: /users',
'标签: 用户管理',
'接口: 3 个',
' GET | /users/{user_id} | get_user | 获取用户详情。',
' PUT | /users/{user_id} | update_user | 更新用户信息。',
' POST | /users/me/avatar | upload_current_user_avatar | 上传当前登录用户头像。',
])
expect(properties(card).at(-1)?.columns).toEqual(['方法', '路径', '函数', '说明'])
expect(card.code).toBe('router = APIRouter(tags=["用户管理"], prefix="/users")')
expect(ROUTES.slice(card.defines?.startIndex, card.defines?.endIndex)).toBe('router')
})
it('函数名带下标(⌘ + 点击跳到接口卡片);路径里的 {user_id} 各讲各的函数的参数;方法用 Swagger UI 的颜色', async () => {
const [getUser, updateUser] = properties(await routerCard(ROUTES, 'router')).at(-1)?.items ?? []
expect(getUser.cells[2]).toEqual([{ text: 'get_user', role: 'function', offset: ROUTES.indexOf('get_user(') }])
const paramOf = (fn: string): number => ROUTES.indexOf('user_id: Int4Path', ROUTES.indexOf(`def ${fn}`))
for (const [row, fn] of [[getUser, 'get_user'], [updateUser, 'update_user']] as const)
expect(flatSegments(row.cells[1]).find(piece => piece.text === 'user_id')?.refers).toEqual({ startIndex: paramOf(fn), endIndex: paramOf(fn) + 'user_id'.length })
expect(updateUser.cells[0]).toEqual([{ text: 'PUT', role: 'keyword', color: { dark: '#fca130', light: '#b35f00' } }])
})
it('接口卡片写挂在哪个路由器上(名字带下标,⌘ + 点击跳到路由器卡片),排在说明后面', async () => {
const rows = properties(await route(ROUTES, 'update_user'))
expect(rows.map(row => row.label).slice(0, 4)).toEqual(['名称', '说明', '路由器', '标签'])
expect(rows[2].value).toEqual([{ text: 'router', role: 'variable', offset: ROUTES.indexOf('router = APIRouter') }])
})
it('写了依赖、默认响应才有这两行;FastAPI 应用没有前缀;变量的说明是属性 docstring;没挂接口时「0 个」、不画表格', async () => {
const source = `${HEADER}"""整个应用。"""
empty = APIRouter()
@router.get("/{item_id}")
def show(item_id: int):
"""看一个物品。
带库存。
"""
@app.post("/items")
def create():
pass
`
expect(propertyLines(properties(await routerCard(source, 'router')))).toEqual([
'名称: router',
'前缀: /items',
'标签: 物品',
'依赖: verify_token',
'默认响应: 401',
' 401 | | 没登录',
'接口: 1 个',
' GET | /items/{item_id} | show | 看一个物品。',
])
expect(propertyLines(properties(await routerCard(source, 'app')))).toEqual([
'名称: app',
'说明: 整个应用。',
'接口: 1 个',
' POST | /items | create | ',
])
const empty = properties(await routerCard(source, 'empty'))
expect(propertyLines(empty)).toEqual(['名称: empty', '接口: 0 个'])
expect(empty.at(-1)?.columns).toBeUndefined()
})
})
describe('fastapi 库规则:别的文件里的定义(工作区索引 + 语言扩展查定义)', () => {
const SCHEMAS = 'backend/src/luffy_agent/core/exceptions/schemas.py'
const PARAMS = 'backend/src/luffy_agent/core/params.py'
+147 -16
View File
@@ -1,4 +1,4 @@
import type { FunctionBlock, ImportFacts, IndexEntry, Inline, KindIconName, LibraryRule, Node, ParameterFacts, PropertyItem, PropertyRow, RuleCard, RuleContext, Segment, ThemeColor, WorkspaceIndex } from '../contract'
import type { FunctionBlock, ImportFacts, IndexEntry, Inline, KindIconName, LibraryRule, Node, ParameterFacts, PropertyItem, PropertyRow, RuleCard, RuleContext, Segment, ThemeColor, VariableBlock, WorkspaceIndex } from '../contract'
import type { Call, LibraryNames } from './pythonTree'
import { callOf, genericOf, lastName, libraryName, stringContent, syntaxChildren, unwrapType } from './pythonTree'
import { hint, joined, name, range, word } from './segments'
@@ -15,6 +15,9 @@ const RULE_ID = 'fastapi'
const KIND = 'fastapi.route'
const COLOR: ThemeColor = { dark: '#61afef', light: '#1a6fb5' }
const ICON: KindIconName = 'globe'
const ROUTER_KIND = 'fastapi.router'
const ROUTER_COLOR: ThemeColor = { dark: '#7aa2f7', light: '#34548a' }
const ROUTER_ICON: KindIconName = 'network'
/** 认路由对象、参数标记、HTTPException 时看从这几个库导入的名字(HTTPException、status 也可以从 starlette 来)。 */
const NAME_LIBRARIES = ['fastapi', 'starlette']
@@ -63,12 +66,17 @@ type Place = 'path' | 'query' | 'header' | 'cookie' | 'body' | 'dependency'
/** 一种显示语言的用词。 */
interface Words {
/** 接口卡片、路由器卡片的种类名 */
kind: string
labels: Record<'name' | 'doc' | 'tags' | 'async' | 'decorators' | 'dependencies' | 'request' | 'responses', string>
routerKind: string
labels: Record<'name' | 'doc' | 'router' | 'tags' | 'async' | 'decorators' | 'dependencies' | 'request' | 'responses' | 'prefix' | 'defaultResponses' | 'routes', string>
yes: string
no: string
count: (n: number) => string
requestHeads: string[]
responseHeads: string[]
/** 路由器卡片的接口表:方法 | 路径 | 函数 | 说明 */
routeHeads: string[]
items: Record<'url' | 'method' | 'path' | 'query' | 'header' | 'cookie' | 'body', string>
/** 成功那一行没写 response_description 时的说明 */
success: string
@@ -86,11 +94,27 @@ interface Words {
const ZH: Words = {
kind: '接口',
labels: { name: '名称', doc: '说明', tags: '标签', async: '异步', decorators: '装饰器', dependencies: '依赖', request: '请求', responses: '响应' },
routerKind: '路由器',
labels: {
name: '名称',
doc: '说明',
router: '路由器',
tags: '标签',
async: '异步',
decorators: '装饰器',
dependencies: '依赖',
request: '请求',
responses: '响应',
prefix: '前缀',
defaultResponses: '默认响应',
routes: '接口',
},
yes: '是',
no: '否',
count: n => `${n} 个`,
requestHeads: ['项', '值'],
responseHeads: ['状态码', '内容', '说明'],
routeHeads: ['方法', '路径', '函数', '说明'],
items: { url: 'URL', method: '方法', path: '路径参数', query: '查询参数', header: '请求头', cookie: 'Cookie', body: '请求体' },
success: '成功',
validation: '参数校验失败',
@@ -225,6 +249,8 @@ function listItems(node: Node | undefined): Node[] {
/** 路由对象:同一文件模块顶层 `X = APIRouter(...)` / `X = FastAPI(...)` 赋值出来的,和它给挂在上面的接口叠的东西。 */
interface Router {
/** 赋值目标:路由对象的名字 */
target: Node
prefix?: Node
tags: Node[]
dependencies: Node[]
@@ -242,6 +268,7 @@ function routersOf(root: Node, env: Env): Map<string, Router> {
if (target?.type !== 'identifier' || !call || (kind !== 'APIRouter' && kind !== 'FastAPI'))
continue
routers.set(target.text, {
target,
prefix: kind === 'APIRouter' ? call.keywords.get('prefix') : undefined,
tags: listItems(call.keywords.get('tags')),
dependencies: listItems(call.keywords.get('dependencies')),
@@ -272,6 +299,40 @@ function routeOf(decorator: Node, routers: ReadonlyMap<string, Router>): Route |
return { decorator, router, method: method.toUpperCase(), call, path: call.positional[0] ?? call.keywords.get('path') }
}
/** 路由器卡片接口表里的一个接口:挂在这个路由对象上的函数(模块顶层的)。 */
interface RouteOn {
route: Route
definition: Node
name: Node
}
/** 这份文件模块顶层挂在 router 上的接口,照源码顺序;一个函数几个路由装饰器时同接口卡片,取第一个。 */
function routesOn(root: Node, routers: ReadonlyMap<string, Router>, router: Router): RouteOn[] {
return syntaxChildren(root).flatMap((statement) => {
const definition = statement.type === 'decorated_definition' ? statement.childForFieldName('definition') : null
const name = definition?.type === 'function_definition' ? definition.childForFieldName('name') : null
if (!definition || !name)
return []
const route = syntaxChildren(statement).filter(child => child.type === 'decorator').map(decorator => routeOf(decorator, routers)).find(found => found !== undefined)
return route?.router === router ? [{ route, definition, name }] : []
})
}
/** 函数的参数名 → 定义处那个名字(`*args` 这种不算),路径里 `{参数}` 讲的是它。 */
function parametersOf(definition: Node): Map<string, Node> {
const names = syntaxChildren(definition.childForFieldName('parameters')).map(param =>
param.type === 'identifier' ? param : param.type === 'typed_parameter' ? syntaxChildren(param)[0] : param.childForFieldName('name'))
return new Map(names.flatMap(param => param?.type === 'identifier' ? [[param.text, param] as const] : []))
}
/** 函数 docstring 的第一行(翻译插件取的说明原文),没有 docstring 时没有。 */
function docFirstLine(definition: Node, env: Env): string | undefined {
const [first] = syntaxChildren(definition.childForFieldName('body'))
const [doc] = first?.type === 'expression_statement' ? syntaxChildren(first) : []
const markdown = doc?.type === 'string' ? env.context.doc(doc)?.markdown : undefined
return markdown?.split('\n').map(line => line.trim()).find(line => line !== '')
}
/**
* 路径里的一段:`{参数}` 按变量着色,其余按字符串,都带源码下标;花括号里的名字讲的是函数的同名参数(params),
* 标上 refers,高亮参数的各处出现时它也跟着亮、⌘ + 点击跳到参数。写的不是字符串时交给翻译插件翻。
@@ -544,6 +605,25 @@ function addRaises(body: Node | null | undefined, statuses: Statuses, env: Env):
}
}
/** 响应那一行:值是各状态码用 ` / ` 连起来,下面一张表格「状态码 | 内容 | 说明」(同一行里的内容「、」隔开,消息「;」隔开)。 */
function responsesRow(label: string, statuses: Statuses, env: Env): PropertyRow {
const { words } = env
const rows = statuses.rows()
return {
label,
value: [hint(rows.map(row => textOf(row.code)).join(' / '))],
columns: words.responseHeads,
items: rows.map(row => ({
cells: [row.code, joined(row.contents, hint(words.listSeparator)), joined(row.notes, { text: words.messageSeparator, role: 'comment' })],
})),
}
}
/** HTTP 方法:大写,按 Swagger UI 的配色(没有配色的按关键字着色)。 */
function methodText(method: string): Inline[] {
return [{ text: method, role: 'keyword', ...(METHOD_COLORS[method] && { color: METHOD_COLORS[method] }) }]
}
/** 请求表的一行:项 | 值。 */
function requestItem(label: string, value: Inline[]): PropertyItem {
return { cells: [[hint(label)], value] }
@@ -565,7 +645,7 @@ function routeCard(block: FunctionBlock, route: Route, env: Env): RuleCard {
const url = [...pathSegments(router.prefix, params, env), ...pathSegments(route.path, params, env)]
const request: PropertyItem[] = [
requestItem(words.items.url, url),
requestItem(words.items.method, [{ text: route.method, role: 'keyword', ...(METHOD_COLORS[route.method] && { color: METHOD_COLORS[route.method] }) }]),
requestItem(words.items.method, methodText(route.method)),
...(['path', 'query', 'header', 'cookie'] as const).flatMap(place => at(place).length > 0 ? [requestItem(words.items[place], paramsText(at(place), env))] : []),
...(body.length > 0 ? [requestItem(words.items.body, body.length === 1 && body[0].type ? context.translate(body[0].type) : paramsText(body, env))] : []),
]
@@ -587,7 +667,6 @@ function routeCard(block: FunctionBlock, route: Route, env: Env): RuleCard {
addRaises(definition?.childForFieldName('body'), statuses, env)
if (placed.some(item => item.place !== 'dependency'))
statuses.add(numericStatus('422'), [hint(words.validation)], [hint(words.automatic)])
const responses = statuses.rows()
const doc = facts.doc && context.doc(facts.doc)
const tags = [...router.tags, ...listItems(call.keywords.get('tags'))].map(tag => tagText(tag, env))
@@ -602,6 +681,7 @@ function routeCard(block: FunctionBlock, route: Route, env: Env): RuleCard {
const rows: PropertyRow[] = [
...(facts.name ? [{ label: labels.name, value: [name(facts.name, 'function')] }] : []),
...(doc ? [{ label: labels.doc, value: doc }] : []),
{ label: labels.router, value: [name(router.target, 'variable')] },
...(tags.length > 0 ? [{ label: labels.tags, value: joined(tags, separator) }] : []),
{ label: labels.async, value: [word(facts.async ? words.yes : words.no)] },
...(decorators.length > 0 ? [{ label: labels.decorators, value: joined(decorators.map(other => context.translate(other)), { text: '\n', role: 'plain' }) }] : []),
@@ -612,14 +692,7 @@ function routeCard(block: FunctionBlock, route: Route, env: Env): RuleCard {
columns: words.requestHeads,
items: request,
},
{
label: labels.responses,
value: [hint(responses.map(row => textOf(row.code)).join(' / '))],
columns: words.responseHeads,
items: responses.map(row => ({
cells: [row.code, joined(row.contents, separator), joined(row.notes, { text: words.messageSeparator, role: 'comment' })],
})),
},
responsesRow(labels.responses, statuses, env),
]
return {
kind: KIND,
@@ -631,21 +704,79 @@ function routeCard(block: FunctionBlock, route: Route, env: Env): RuleCard {
}
}
/**
* 路由器卡片:名称 / 说明 / 前缀 / 标签 / 依赖 / 默认响应(有才显示),接口表列这份文件里挂在它上面的全部接口:
* 方法 | 路径(前缀 + 装饰器里的路径,`{参数}` 讲那个函数的参数)| 函数(⌘ + 点击跳到那张接口卡片)| 说明(docstring 第一行)。
*/
function routerCard(block: VariableBlock, router: Router, routes: readonly RouteOn[], env: Env): RuleCard {
const { context, words } = env
const { labels } = words
const separator = hint(words.listSeparator)
const doc = block.facts.doc && context.doc(block.facts.doc)
const tags = router.tags.map(tag => tagText(tag, env))
const dependencies = listedDependencies(router.dependencies, env)
const statuses = new Statuses()
addResponses(router.responses, statuses, env)
const rows: PropertyRow[] = [
{ label: labels.name, value: [name(router.target, 'variable')] },
...(doc ? [{ label: labels.doc, value: doc }] : []),
...(router.prefix ? [{ label: labels.prefix, value: pathSegments(router.prefix, new Map(), env) }] : []),
...(tags.length > 0 ? [{ label: labels.tags, value: joined(tags, separator) }] : []),
...(dependencies.length > 0 ? [{ label: labels.dependencies, value: joined(dependencies, separator) }] : []),
...(statuses.rows().length > 0 ? [responsesRow(labels.defaultResponses, statuses, env)] : []),
{
label: labels.routes,
value: [hint(words.count(routes.length))],
...(routes.length > 0 && {
columns: words.routeHeads,
items: routes.map(({ route, definition, name: fn }) => {
const params = parametersOf(definition)
const doc = docFirstLine(definition, env)
return {
cells: [
methodText(route.method),
[...pathSegments(router.prefix, params, env), ...pathSegments(route.path, params, env)],
[name(fn, 'function')],
doc ? [{ text: doc, role: 'comment' }] : [],
],
}
}),
}),
},
]
return {
kind: ROUTER_KIND,
badge: { label: words.routerKind, color: ROUTER_COLOR, icon: ROUTER_ICON },
rows,
defines: range(router.target),
absorbs: [],
}
}
export const fastapiRule: LibraryRule = {
id: RULE_ID,
label: 'FastAPI 接口',
languageIds: ['python'],
libraries: ['fastapi'],
claim: (block, context) => {
if (block.kind !== 'function' || block.facts.decorators.length === 0)
return undefined
const env: Env = { context, words: WORDS[context.displayLanguage ?? ''] ?? ZH, names: namesOf(context.imports) }
const routers = routersOf(block.node.tree.rootNode, env)
const root = block.node.tree.rootNode
if (block.kind === 'function' && block.facts.decorators.length > 0) {
const routers = routersOf(root, env)
for (const decorator of block.facts.decorators) {
const route = routeOf(decorator, routers)
if (route)
return routeCard(block, route, env)
}
}
// 路由对象只认模块顶层的赋值(routersOf),按赋值目标的位置认出是不是这一块
if ((block.kind === 'const' || block.kind === 'variable') && block.facts.declarators.length === 1) {
const routers = routersOf(root, env)
const target = block.facts.declarators[0].name
const router = routers.get(target.text)
if (router?.target.startIndex === target.startIndex)
return routerCard(block, router, routesOn(root, routers, router), env)
}
return undefined
},
attributeNames: displayLanguage => ({ attributes: { [METHOD_ATTRIBUTE]: (WORDS[displayLanguage ?? ''] ?? ZH).methodAttribute }, values: {} }),
@@ -14,6 +14,7 @@ import {
ListOrdered,
Lock,
MessageSquareText,
Network,
Package,
Repeat,
ServerCog,
@@ -52,6 +53,7 @@ export const KIND_ICON_COMPONENTS: Record<KindIconName, LucideIcon> = {
'server-cog': ServerCog,
'calendar-clock': CalendarClock,
'globe': Globe,
'network': Network,
}
/**
+1 -1
View File
@@ -78,7 +78,7 @@ export interface ThemeColor { dark: string, light: string }
export type KindIconName
= | 'import' | 'square-function' | 'box' | 'braces' | 'list-ordered' | 'triangle-alert' | 'tag' | 'lock' | 'variable'
| 'split' | 'corner-down-right' | 'repeat' | 'shield' | 'shield-alert' | 'shield-check' | 'corner-down-left' | 'code'
| 'message-square-text' | 'database' | 'package' | 'server-cog' | 'calendar-clock' | 'globe'
| 'message-square-text' | 'database' | 'package' | 'server-cog' | 'calendar-clock' | 'globe' | 'network'
/** 库规则的种类:名字(悬停提示、读屏念的文字)、颜色和图标(从 KindIconName 里挑);块左边只画图标 */
export interface KindBadge { label: string, color: ThemeColor, icon: KindIconName }