FROWNINGdev/orm-lens
FROWNINGdev/orm-lens has 112 GitHub stars and 42 forks. GitHot measured +1 stars in 24 hours, +12 in 7 days, and +15 in 15 days. Last checked 2026-11-18 22:30 UTC. Last push 2026-11-15.
可以做什么
- PR review bot for schema changes — posts once, then updates in place - blast-radius + the Action
- Analysis that follows a queryset across functions - nplusone
- Schema drift detection - drift
- Index proposals from observed QuerySet usage - suggest-indexes
实测星标增长
- 24小时
- +1
- 7天
- +12
- 15天
- +15
- 1个月
- 正在收集历史
各周期内的星标净变化,周期相互重叠,并非每日新增。缺失的测量保持空白。星标代表关注度,不代表软件质量。
关于
ER diagrams, N+1 detection, schema drift & migration-risk linting for Django and SQLAlchemy (Alembic) — VS Code, CLI and MCP server. Static analysis: no database, no app boot. Free & MIT. Formerly django-orm-lens.
开发工具docs/i18n/README.zh.md
原文English · Русский · Español · 中文

ORM Lens
Django 的 ER 图、N+1 检测与迁移风险检查 —— 无需启动项目。
你的整张模型图 —— 实时呈现在编辑器侧边栏、为你的 CI 把关,并通过 MCP 回答你的 AI agent 的提问。全部来自静态解析:无需数据库、无需 runserver、无需可用的 venv。
取代: graph_models + django-schema-graph + 手绘 ER 图 + grep 考古。
⚡ 10 秒获得第一份洞察
uvx orm-lens scan -f table # every app and model at a glance
uvx orm-lens nplusone # N+1 loops, with the select_related to add
uvx orm-lens migration-risk # migrations that lock tables or fail on existing rows
冷克隆、坏掉的 venv、没有 settings 模块 —— 你依然能在终端里看到项目的每个 app 和模型,以及其中的 N+1 循环和高风险迁移。(uvx 来自 uv;pipx run 用法相同。)
接着选择你的使用面 —— 三种发行形式,同一个解析器内核:
| 你是谁 | 安装 | 你将得到 |
|---|---|---|
| 编辑器用户 —— VS Code / Cursor / Windsurf / VSCodium | code --install-extension frowningdev.django-orm-lens |
侧边栏树形视图、实时 ER 图、悬停卡片、16 条 QuickFix 规则 |
| 终端 / CI 用户 | pip install orm-lens |
13 个子命令、SARIF + PR 注解、pre-commit 钩子、一个 GitHub Action |
| AI agent 用户 —— Cursor / Claude Code / Aider / Zed / Continue | pip install "orm-lens[mcp]" |
14 个只读 MCP 工具,基于确凿事实回答数据结构问题 |
MCP 配置只需一段 JSON —— 参见 Integrations。将 ORM_LENS_ROOT 指向你的 Django 项目的绝对路径。
🆓 别处收费的能力,这里免费且遵循 MIT 协议
模式审查几乎在哪里都是付费品类。逐个审查拉取请求的机器人、能把 queryset 追踪到其构建函数之外的分析、发现模式与迁移不一致的检查、基于真实表统计给出的索引建议 —— 这些通常都在按席位或按数据库计费的订阅背后。
这里全都有,采用 MIT 协议:没有分级、不数席位、无需账号、不含遥测。
| 通常需要付费的能力 | 这里 |
|---|---|
| 模式变更的 PR 审查机器人 —— 只发一条,之后原地更新 | blast-radius + Action |
| 跨函数追踪 queryset 的分析 | nplusone |
| 模式漂移检测 | drift |
| 依据实际 QuerySet 用法提出索引建议 | suggest-indexes |
| 结合真实表体量衡量迁移风险 | blast-radius --stats |
| 破坏性迁移的影响范围 | blast-radius |
| 删除字段会波及什么 —— 按 Django 分层 | impact |
没有 Pro 版本,也没有相关计划。 如果它替你省下一个下午,点个 star 就是全部的请求。
📊 项目动态
如果这个工具下次帮你在一个陌生的 Django 项目里省掉一次
grep—— 一颗 star 能帮助更多人发现它。
📈 Star 增长
⚡ 安装
VS Code / Cursor / Windsurf(VS Code Marketplace):
code --install-extension frowningdev.django-orm-lens
VSCodium / code-server / Gitpod / 任意开源 Code 派生版(Open VSX):
codium --install-extension frowningdev.django-orm-lens
或者在扩展视图中搜索 ORM Lens —— 两个市场上的发布者都是同一个 frowningdev。
终端与 AI 编码 agent:
pip install orm-lens # CLI only
pip install "orm-lens[mcp]" # + MCP server for AI agents
需要 Python 3.9+(MCP 服务器需要 3.10+)。CLI 运行时零依赖。
Docker(v0.6+):
docker run --rm -v "$PWD:/workspace" ghcr.io/frowningdev/orm-lens scan --path .
多架构(amd64 + arm64)。宿主机无需 Python。适合 CI 与一次性审计。
🎯 待解决的问题
离线可用。venv 坏了也能用。在别人的电脑上也能用。在 CI 里也能用。
你打开一个 Django 项目。它有 20 个 app。你需要回答一个简单的问题:
"哪个 app 拥有
Order模型?它是怎么和User关联的?"
今天,这意味着:Ctrl+P,输入 "models",在 30 个匹配里滚动,打开五个文件,Ctrl+F 搜 class Order,翻过 400 行 ForeignKey('otherapp.Something') 字符串,努力回忆两个文件之前看到的信息。
半天没了。每次都这样。每个项目都这样。
✨ 有了 ORM Lens
📚 一棵覆盖一切的树每个 app → 每个模型 → 每个字段 → 每个 图标能让你一眼分辨 |
🕸️ 实时 ER 图一条命令即可打开整个数据结构的 Mermaid 实体关系图。编辑代码时它会随之重绘。可导出为 SVG。
|
🔎 悬停查看关系在任意 Python 文件中悬停到 |
🧭 跳转到定义在树中点击任意字段 → 光标精准落在对应行。可按 app 或模型名过滤树形视图。完整支持拆分的 |
⚡ 零配置无需 |
🎨 原生 VS Code UI深色主题、浅色主题、你自定义的主题。遵循你的图标主题、字体和快捷键。不刺眼,不带品牌噪点。 |
🚀 进阶功能
🎯 行内 QuickFix(16 条规则)对 用 |
🧪 Factory 生成器右键任意模型 → 生成 也可通过每个模型类上方的 CodeLens 使用。 |
🕰 时间旅行 Schema Diff选一个 重命名是一等事件,绝不会退化成 |
🔎 影响分析"删掉这个字段会弄坏什么?" —— 右键字段或模型 → 全工作区扫描,按 Django 层级分组(models、serializers、forms、admin、views、urls、templates、tests、migrations)。 每条结果都带 Certain / Likely / Possibly 置信标签。可处理 ORM 字符串引用( |
⚡ 交互式查询构建器右键字段或模型 → 选择模板 → 代码片段插入光标处(带 tab-stop),或插入一个全新的未命名缓冲区。 FK 上的 |
🎨 侧边栏 UX 全面翻新稳定的
|
📸 界面预览
实时示例 — orm-lens er 的真实输出,GitHub 会直接在此渲染:
erDiagram
User {
CharField display_name
}
Tag {
CharField name
}
Post {
CharField title
DateTimeField created_at
}
Comment {
TextField body
}
Post }o--|| User : "author [CASCADE, as posts]"
Post }o--o{ Tag : "tags [as posts]"
Comment }o--|| Post : "post [CASCADE, as comments]"
Comment }o--|| User : "author [SET_NULL]"
扩展中还包含:
- 🕸️ 实时 ER 图 —— Mermaid 基数箭头、连线标签(
CASCADE、through Model、as related_name),主题自适应,一键导出 SVG - 🔎 悬停卡片 —— 覆盖任意
ForeignKey('app.Model')或ManyToManyField(...),附一键跳转链接 - 🧭 CodeLens —— 在每个
class Model行上方显示:字段数、关系数,以及 Open ER diagram 操作 - 🎨 命名主题 —— 图表 webview 的
auto/default/dark/forest/neutral
🤖 面向终端与 AI 编码 agent
驱动 VS Code 扩展的那个解析器同时作为独立的 Python 包发布 —— 并可选配 MCP(Model Context Protocol)服务器,让任意兼容 MCP 的 AI agent 在不导入 Django、也不启动你的应用的情况下浏览你的 Django 数据结构。
CLI
orm-lens scan -f json # every app, every model, every field
orm-lens describe blog.Post # one model in Markdown
orm-lens list | fzf # flat app.Model — pipes anywhere
orm-lens er > schema.mmd # ER diagram — Mermaid (default)
orm-lens er -f dbml > schema.dbml # …or DBML: paste into dbdiagram.io
orm-lens er -f d2 > schema.d2 # …or D2 / plantuml
orm-lens diff before.json after.json # what a PR changes structurally
orm-lens nplusone --format github # N+1 findings as PR annotations
orm-lens migration-risk -f sarif # SARIF for GitHub Code Scanning
orm-lens suggest-indexes blog.Post # Meta.indexes proposals from usage
orm-lens signals # sender→signal→handler graph
orm-lens migration-deps blog -f mermaid # per-app migration DAG
orm-lens cascade blog.Author # what one delete() takes down
每个命令都接受 --path <dir> 与 --exclude <glob>。nplusone / migration-risk / diff 在有发现时以退出码 1 结束 —— 把它们放进 CI,即可在出现回归时拦下 PR。
MCP 服务器
在你的 agent 中注册一次,即可暴露十个只读工具:
| 工具 | 用途 |
|---|---|
list_apps |
工作区中的每个 Django app 及其模型数量 |
list_models |
扁平的 app.Model 列表,可选按 app 过滤 |
describe_model |
单个模型的完整字段 / 关系 / Meta 详情 |
find_relations |
单个模型的入向 + 出向关系 |
cascade_preview |
一次 delete() 的波及范围,按 on_delete 分组 |
er_diagram |
ER 图 —— mermaid / dbml / d2 / plantuml |
describe_migration_dependency |
按 app 的迁移 DAG:根、叶、跨 app 依赖 |
suggest_indexes |
依据观察到的 QuerySet 用法给出 Meta.indexes 建议 |
signal_graph |
来自 @receiver 装饰器的 Sender→signal→handler 图 |
nplusone_scan |
整个工作区的静态 N+1 检测结果 |
# Start it directly
orm-lens-mcp
# Or via the CLI subcommand
orm-lens mcp
工作区解析(py-1.3.0+)。 每个工具在调用时都接受可选的 workspace_root 参数。解析优先级:显式参数 → $ORM_LENS_ROOT → 当前工作目录。无效或非 Django 路径会返回结构化响应({"error": "WORKSPACE_NOT_DJANGO", "hint": "…"})而不是空结果,agent 因此可以自我纠正。可选沙箱通过 ORM_LENS_ALLOWED_ROOTS 设置(Windows 上以 ; 分隔,其他平台以 : 分隔)。
🛡️ 把关你的 CI
数据结构回归在刚进入 PR 的那一刻拦截成本最低。三种零配置的拦截方式:
pre-commit —— 两个钩子,本地无需安装任何东西:
# .pre-commit-config.yaml
repos:
- repo: https://github.com/FROWNINGdev/orm-lens
rev: py-v1.17.1
hooks:
- id: orm-lens-nplusone
- id: orm-lens-migration-risk
GitHub Action —— 检出的问题以 PR 注解呈现,无需任何额外权限:
- uses: FROWNINGdev/orm-lens@action-v1
with:
command: migration-risk # or: nplusone
format: github # ::error / ::warning annotations on the diff
SARIF → Code Scanning —— 检出的问题会进入仓库的 Security 标签页:
- run: |
pip install orm-lens
orm-lens migration-risk --format sarif --exit-zero > lens.sarif
- uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: lens.sarif
退出码天生适配 CI:diff 与 nplusone 在有发现时退出 1,migration-risk 在有严重发现时退出 1。加上 --exit-zero 即为只报告模式。
🔌 集成
| 客户端 | 启用方式 | 状态 |
|---|---|---|
| VS Code | code --install-extension frowningdev.django-orm-lens |
✅ |
| Cursor | 相同的 VSIX + 可选地在 ~/.cursor/mcp.json 中添加 MCP 条目 |
✅ |
| Windsurf / VSCodium / 任意 Code 派生版 | 从 Marketplace 或 GitHub Releases 安装 VSIX | ✅ |
| Aider | 将 orm-lens-mcp 添加到你的 mcp.json |
✅ (via MCP) |
| Continue.dev | 在 ~/.continue/config.json 中注册 MCP 服务器 |
✅ (via MCP) |
| Zed | 在 Zed 设置中注册 MCP 服务器 | ✅ (via MCP) |
| 任意兼容 MCP 的客户端 | 将 command 指向 orm-lens-mcp,并设置 ORM_LENS_ROOT |
✅ |
| pre-commit | repo: https://github.com/FROWNINGdev/orm-lens + 两个 hook id |
✅ |
| GitHub Actions | uses: FROWNINGdev/orm-lens@action-v1 —— 注解或 SARIF |
✅ |
| 可在 MCP Registry 中发现 | 官方 Model Context Protocol 服务器目录 | ✅ |
| 纯终端 / CI | pip install orm-lens && orm-lens scan |
✅ |
示例:Cursor / 任意 MCP 客户端
{
"mcpServers": {
"orm-lens": {
"command": "orm-lens-mcp",
"env": { "ORM_LENS_ROOT": "/abs/path/to/your/project" }
}
}
}
⚡ 性能
回归测试套件解析 Zulip、Saleor、Wagtail、django CMS 与 Mezzanine 内置的模型图 —— 59 个模型、13,478 行真实世界的 models.py —— 在一台笔记本上端到端约 20 ms(在仓库的黄金夹具语料上三次取最佳为 21 ms;CI 的每个矩阵单元都运行一道 <2 s 守卫)。
自己复现一下:
git clone https://github.com/FROWNINGdev/orm-lens && cd orm-lens/cli
pip install -e . && python -m pytest tests/test_golden_fixtures.py tests/test_golden_snapshots.py -q
🎯 适用人群
- Django 开发者 —— 接手一个 10+ apps 的代码库,在
models.py的丛林里迷路。 - 外包 / 自由职业工程师 —— 需要在第一小时内(而不是第一周内)搞懂一个陌生的 Django 项目。
- 在为新员工做入职的团队 —— 想要一眼看清的数据结构视图,而不必额外搭建一套文档基础设施。
- AI agent 重度用户(Cursor / Aider / Zed / Continue / 任意兼容 MCP 的客户端)—— 需要 agent 准确回答关于数据结构的问题,同时又不必给它数据库凭据或启动 Django。
- CI 流水线 —— 校验数据结构形态(例如 "我们是不是不小心破坏了某个
related_name?"),无需导入项目。 - 单干的独立开发者 —— venv 坏了、在别人的电脑上工作 —— 无需
runserver,无需manage.py migrate,依然可用。
🗺️ 市场定位
ORM Lens 处在 编辑器工具 与 AI agent 工具 的交叉地带 —— 一个现有软件包都没有覆盖的位置:
| 细分 | 现有方案 | 代价 |
|---|---|---|
| 启动后生成图 | django-extensions graph_models |
需要 Graphviz + Django settings + 可用的 DB URL |
| Web 查看器 | django-schema-graph |
需要运行中的 Django 服务器;又多一个可能出故障的东西 |
| 管理面板 | Django Admin | 需要 runserver + 认证 + 数据库 —— 适合看数据,不适合看架构 |
| 编辑器插件 | PyCharm 的 Django Structure | 锁定 PyCharm;没有 CLI,没有 AI agent 入口 |
| MCP 服务器 | (此前没有) | AI agent 只能从源码里靠猜来理解你的数据结构,不完美 |
ORM Lens 是唯一一个基于同一个解析器同时提供三种形态的工具: 一个 VS Code 扩展(任意 Code 派生版)、一个零依赖 CLI(终端 + CI),以及一个 MCP 服务器(AI agent)。全部静态。全部免费。全部 MIT。
🤔 它与众不同在哪里?
| ORM Lens | django-extensions graph_models |
django-schema-graph |
Django Admin | PyCharm Django Structure | |
|---|---|---|---|---|---|
| 无需可启动的 Django 项目也能工作 | ✅ | ❌ | ❌ | ❌ | ⚠️ |
| 零安装(无 graphviz、无服务器) | ✅ | ❌ | ❌ | ❌ | ❌(需要 PyCharm) |
| 在 VS Code / Cursor / 任意 Code 派生版中工作 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 编辑器内侧边栏树形视图 | ✅ | ❌ | ❌ | ❌ | ✅ |
| 实时 ER 图 | ✅ | ✅ | ✅ | ❌ | ❌ |
ForeignKey 悬停卡片 |
✅ | ❌ | ❌ | ❌ | ⚠️ |
| 模型类上的 CodeLens | ✅ | ❌ | ❌ | ❌ | ❌ |
拆分的 models/ 包支持 |
✅ | ⚠️ | ⚠️ | ✅ | ✅ |
| 面向终端 / CI 的 CLI | ✅ | ⚠️ | ❌ | ❌ | ❌ |
| 面向 AI agent 的 MCP 服务器 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 可在 MCP Registry 中发现 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 免费开源(MIT) | ✅ | ✅ | ✅ | ✅ | ❌(付费 IDE) |
| Django 版本支持 | 4.0 – 6.1 | latest | 3.2 – 4.1(自 2023 起停更) | latest | latest |
django-schema-graph自 2023-05 起未再更新,且未测试 Django 5.x。
当你需要别的东西时
坦诚的边界:剖析一个在线请求 → django-debug-toolbar。历史请求剖析 → django-silk。测试套件内的查询计数断言 → django-perf-rec。真实流量上的生产 APM → Scout / Sentry。ORM Lens 刻意保持静态 —— 它是在应用还无法启动之前就能工作的那一层,也是你的 CI 和 AI agent 在任何 checkout 上都能用的唯一一层。
⚙️ 配置
默认值经过精心设计,通常够用。如果你需要调整:
// .vscode/settings.json
{
"djangoOrmLens.excludeGlobs": [
"**/migrations/**",
"**/node_modules/**",
"**/venv/**",
"**/.venv/**",
"**/env/**"
],
"djangoOrmLens.autoRefresh": true
}
| 设置项 | 类型 | 默认值 | 作用 |
|---|---|---|---|
djangoOrmLens.excludeGlobs |
string[] |
见上方 | 扫描时要跳过的 glob 模式 |
djangoOrmLens.autoRefresh |
boolean |
true |
在 models.py 变化时重新扫描 |
djangoOrmLens.codeFixes.enabled |
boolean |
true |
DOL### 诊断 + QuickFix 的总开关 |
djangoOrmLens.rules |
object |
{} |
按规则的严重级别:{ "DOL007": "off", "DOL013": "error" } |
djangoOrmLens.rulesSelect |
string[] |
[] |
Ruff 风格的 select。["DOL0"] 只运行 queryset+model 规则 |
djangoOrmLens.rulesIgnore |
string[] |
[] |
Ruff 风格的 ignore。["DOL03"] 静默 form/view 规则 |
🔬 规则目录
十六条编辑器端检查(DOL001–DOL032),带 Ruff 风格规则码、按规则的严重级别与 Clippy 风格的 applicability —— 外加十五条 CLI 端迁移风险规则和静态 N+1 分析器。现在每条规则都有自己的文档页。
| 类别 | 规则 | 示例 |
|---|---|---|
| Queryset | DOL001–DOL007 |
.count() > 0 → .exists()、循环中访问 FK(N+1) |
| 模型定义 | DOL011–DOL015 |
缺少 on_delete 的 ForeignKey、字符串字段上的 null=True |
| 日期时间 | DOL021 · DOL022 |
datetime.now() → timezone.now() |
| 表单 / 视图 | DOL031–DOL032 |
render() 中使用 locals()、Meta.fields = '__all__' |
| 迁移风险 | 16 条规则 | 无默认值的 NOT NULL 新增、锁表的索引构建、不可逆的数据迁移 |
| 静态 N+1 | 1 个分析器 | 循环中访问 FK/M2M 而未用 select_related / prefetch_related |
→ 完整规则参考 —— 每个规则码都附有反例/正例、QuickFix 行为与抑制语法。
行内抑制
# orm-lens-disable-next-line DOL007
for user in User.objects.all():
print(user.profile) # not flagged
qs.count() > 0 # orm-lens-disable-line DOL001
# orm-lens-disable DOL011 ← on its own line, kills DOL011 for the rest of the file
Applicability 沿用 Rust 的 Clippy:safe 修复可以自动应用("Fix All"),suggestion 修复以 QuickFix 的形式提供但需人工确认,unsafe 发现绝不自动应用。修复器与分析器相互分离(Roslyn 风格),因此一条规则可以随时间生长出多个修复器,而无需触碰检测逻辑。
🧭 命令
打开命令面板(Ctrl+Shift+P / Cmd+Shift+P),输入 "ORM Lens":
| 命令 | 作用 |
|---|---|
ORM Lens: Refresh |
强制重新扫描工作区 |
ORM Lens: Show ER Diagram |
在代码旁边打开 Mermaid ER 图 |
ORM Lens: Filter Models |
按 app / 模型 / 字段名过滤树形视图 |
ORM Lens: Clear Filter |
恢复完整的树形视图 |
ORM Lens: Jump to Model |
程序化触发 —— 由树中点击与悬停卡片调用 |
ORM Lens: Find Reverse References |
右键模型 —— QuickPick 列出指向它的每个 FK |
ORM Lens: Generate factory_boy Factory |
右键模型或使用 CodeLens —— 生成 DjangoModelFactory 脚手架 |
ORM Lens: Schema Diff (Time-Travel) |
选两个 commit —— 在 markdown 缓冲区中得到类型化 diff |
ORM Lens: Find Impact (What Uses This?) |
右键字段或模型 —— 全工作区引用扫描 |
ORM Lens: Build Query (Insert Snippet) |
右键字段或模型 —— 选择一个 ORM 模板 |
🗺️ 路线图
已发布
- 按 app 分组的侧边栏树形视图
- 实时 Mermaid ER 图
-
ForeignKey('app.Model')悬停卡片 - 按名称过滤树形视图
- 拆分的
models/包支持 - 将 ER 图导出为 SVG
- 面向终端与 AI agent 的 Python CLI + MCP 服务器
- 空工作区的欢迎视图
- 路径安全的跳转到定义与经过净化的悬停 markdown
- v0.3.0 —— 每个模型类上方的 CodeLens(
N fields · N relations · Open ER diagram) - v0.3.0 —— 图表上的连线标签(
CASCADE、SET_NULL、PROTECT、related_name) - v0.3.0 —— 命名的颜色主题(
auto/default/dark/forest/neutral) - v0.3.1 —— M2M 连线上的
through_model(由 @kingrubic 贡献) - v0.3.1 —— 收录到 官方 MCP Registry 与 Glama.ai
- v0.6.0 —— CLI
nplusone—— 静态 N+1 检测器(循环内访问 FK/M2M 而未用select_related/prefetch_related) - v0.6.0 —— CLI
migration-risk—— 标记migrations/*.py中的危险操作(目前 15 条规则) - v0.6.0 —— CLI
diff—— 比较两份 schema JSON 导出,用于 PR 评审 - v0.6.0 —— ER 图缩略图按 Django app 为节点着色
- v0.6.0 —— README 翻译:🇷🇺 俄语、🇪🇸 西班牙语、🇨🇳 中文
- v0.6.0 —— GHCR 上的 Docker 镜像:
docker run ghcr.io/frowningdev/orm-lens - v0.7.0 ——
settings.AUTH_USER_MODEL在所有位置都能解析:n+1 反向关系、信号 sender、Mermaid ER、VS Code webview、入向关系面板、React ER - v0.7.0 —— 基于 AST 的字段解析器:
ForeignKey(on_delete=CASCADE, to='User')无论 kwarg 顺序如何都能解析(Python 与 TS 行为一致) - v0.7.0 —— 公开的共享辅助函数:
find_user_model、resolve_related_tail、find_model、iter_workspace_py_files(Python)+findUserModel、resolveRelatedTail(TS) - v0.7.0 ——
--verbose不再把目录树遍历两遍;文件计数由WorkspaceIndex.scanned_files提供 - v0.7.3 —— 字段上的 PEP-526 类型注解(
jti: CharField[str] = models.CharField(...))现在可以解析 —— 由 @jsabater 报告(#25),并附上了干净的 Django Ninja 1.6 复现 - v0.7.4 —— PEP-695 泛型类头(Python 3.12+):
class Container[T](models.Model):现在可以解析 - v0.7.5 —— 现在能检测别名化的 models 模块(
from django.db import models as m)与第三方字段包(jsonfield.JSONField) - v0.7.6 —— Tab 缩进的模型体现在可以解析(默认使用 tab 的编辑器不再显示空模型)
- v0.8.0 —— 行内 QuickFix:16 条规则(
DOL001..DOL032),支持按规则的严重级别 + Ruff 风格 select/ignore + 行内# orm-lens-disable-next-line - v0.8.0 —— Factory 生成器:从任意模型生成
factory_boy脚手架,Faker provider 按字段类型匹配 - v0.8.0 —— 时间旅行 Schema Diff:选两个 commit → 类型化 markdown diff,重命名检测为一等公民
- v0.8.0 —— 影响分析:跨每个 Django 层级的全工作区字段引用扫描,带 Certain/Likely/Possibly 置信标签
- v0.8.0 —— 交互式查询构建器:右键 → 模板 → 片段插入光标处,语法感知(FK 会追加
.select_related,尊重related_name) - v0.8.0 —— 侧边栏 UX 全面翻新:稳定的
TreeItem.id、带command:深层链接的MarkdownString工具提示、FileDecorationProvider徽标、活动栏上的TreeView.badge、三个由 when 条件门控的viewsWelcome状态
未发布(位于 main)
- CI 输出格式:SARIF 2.1.0 +
nplusone与migration-risk的--format githubPR 注解 - 四个分析器从 MCP 专属提升到 CLI:
suggest-indexes、signals、migration-deps、cascade -
er --format dbml | d2 | plantuml—— 社区标准的图表导出(dbdiagram.io、D2、PlantUML) - 三条新的迁移风险规则:
runpython_no_reverse、alter_unique_together_lock、alter_index_together_deprecated—— 共 15 条 - pre-commit 钩子(
django-orm-lens-nplusone、django-orm-lens-migration-risk)+ 复合 GitHub Action -
docs/rules/—— 每条规则一个文档页(19 页) - 覆盖 59 个真实世界模型的黄金快照回归套件(Zulip / Saleor / Wagtail / django CMS / Mezzanine);ruff + mypy 现在把关 CI
- 迁移依赖图 ——
migration-deps(text / json / mermaid)
下一步
-
.filter()/.exclude()/.annotate()内的 ORM 查询自动补全(#3) - app / 模型显隐勾选框,为庞大的数据结构化繁为简
- DOL 规则引擎移植到 Python CLI —— 一份规则目录,三种使用面
长期
- 第三方字段支持(
django-mptt、django-taggit、django-model-utils) - JetBrains / PyCharm 插件(如有需求)
用 👍 为对应的 issue 投票。
❓ 常见问题
会把我的代码发到某台服务器上吗?
不会。每一个字节都留在你的机器上。解析器是纯 TypeScript(扩展)或纯 Python(CLI)。无 LLM 调用、无遥测、无分析、无错误上报。Mermaid 渲染器在 VS Code 的 webview 沙箱内运行。
它能配合 Poetry / uv / conda / 或者根本没有 venv 工作吗?
可以。扩展直接读取 Python 源码 —— 不导入 Django,也不关心你用什么包管理器。CLI 只需要 Python 3.9+,仅此而已。
我的模型拆分到了 models/ 包下的多个文件里。这样能工作吗?
可以,自 v0.2.0 起。扩展与 CLI 都会在遍历经典
models.py 的同时遍历 models/*.py。
能配合 DRF serializers、Wagtail、Oscar 或第三方基类模型吗?
任何看起来像 Django 模型的类都会被识别:
models.Model 的子类、以 Abstract 开头的抽象基类、以 Mixin 结尾的常见混入,以及像 TimeStampedModel 或 PolymorphicModel 这样的已知基类名。非模型类(ModelAdmin、ModelSerializer、Form、View、Manager、……)会被过滤掉。
哪些 AI agent 可以使用 MCP 服务器?
任何兼容 MCP 的客户端 —— Cursor、Aider、Continue.dev、Zed,以及任何其他支持该协议的工具。只需将
command 指向已安装的 orm-lens-mcp 可执行文件即可。详见 Integrations 章节。
如何在 CI 中拦截数据结构回归?
三种方式,全部零配置:两个 pre-commit 钩子、复合 GitHub Action(
uses: FROWNINGdev/orm-lens@action-v1 配合 format: github 输出 PR 注解),或将 --format sarif 管道到 github/codeql-action/upload-sarif 送入 Security 标签页。diff / nplusone 在有发现时退出 1,migration-risk 在有严重发现时退出 1。
有 JetBrains / PyCharm 版本吗?
暂时没有。PyCharm 的 Django Structure 工具窗口本身就不错,价值增量会小一些。如果有足够多的人提出需求,就值得去做。
🆘 支持
- 🐛 Bug 反馈 —— GitHub Issues(请附上最小可复现的
models.py片段) - 💡 功能建议 / 想法 —— GitHub Discussions
- 📝 Marketplace 评价 —— 为扩展打分(推动项目前进最快的信号)
- 🐍 PyPI 页面 —— pypi.org/project/orm-lens
- 💚 赞助 —— github.com/sponsors/FROWNINGdev
📜 许可证
MIT © FROWNINGdev
为在意自己代码库的开发者而生。
Marketplace · PyPI · GitHub · Issues · Discussions · Sponsor