supabase-python

supabase-python 技能概览

supabase-python 是做什么的

supabase-python 技能帮助你用 FastAPI、Supabase Auth 和 SQLAlchemy/SQLModel 搭建 Python 后端。它最适合那种希望让 Supabase 服务发挥最强项、同时又想在 Python 里直接、类型安全地访问核心业务数据的团队。

适合谁使用

如果你正在对接 API、添加登录/会话流程，或者把认证/存储与关系型数据访问分开，supabase-python 技能就很适合你。对于需要一份实用的 Supabase Python 指南，而不是一段泛泛而谈的 Supabase 提示词的 Python 后端开发场景，它尤其合适。

它优化的重点是什么

这个技能的核心模式很清晰：用 SQLAlchemy/SQLModel 处理查询，用 Supabase 负责认证、存储和 realtime。也正因为如此，它适合那些重视可维护的 API 代码、可预测的数据库访问，以及尽量减少 ORM “魔法”假设的场景。

什么时候适合，什么时候不太适合

它最适合带有 Supabase 后端的 FastAPI 应用。如果你的整个应用都依赖 Supabase client 调用，或者你需要的是前端优先的工作流，那它的价值就会小很多。如果你不用 FastAPI，或者不想在 Python 侧维护数据库模型，这个技能就会比通用 Supabase 提示词更窄。

如何使用 supabase-python 技能

正确安装并挂载它

先走仓库里的技能安装流程，然后把这个技能对准一个带 FastAPI API 层、并使用 Supabase 作为后端工作流的 Python 项目。一个典型的安装命令是：
npx skills add alinaqi/claude-bootstrap --skill supabase-python

给技能一个正确的起始 brief

supabase-python 的安装效果最好时，你的提示里要明确三件事：技术栈、数据库与认证的分工、以及你想实现的功能。例如：“给这个 FastAPI app 加上 Supabase 邮箱登录，用户记录继续放在 SQLModel 里，上传的头像存到 Supabase Storage。”这远比“帮我设置 Supabase”更有用。

先读对文件

先看 SKILL.md，然后再检查 README.md 或仓库里任何专门的文档（如果有的话），以及 pyproject.toml、src/main.py、src/core/config.py、src/db/models.py、src/api/deps.py，还有任何 supabase/ 下的 migration 或配置文件。这个仓库里没有额外的 rules 或 resources 目录，所以主要价值来自技能正文和你的项目文件。

采用与这个技能匹配的工作流

一个好的 supabase-python 工作流是：先定义认证需求，再梳理数据库实体，决定哪些数据留在 Postgres，哪些交给 Supabase 服务，最后实现路由和依赖注入。如果一上来就要求它一次性把所有东西都做完，输出更容易把认证、存储和数据库访问混成一个脆弱的模式。

supabase-python 技能 FAQ

supabase-python 只适用于 FastAPI 项目吗？

是的，这就是它的设计重心。这个技能是围绕 FastAPI 模式编写的，所以如果你的应用使用 Django、Flask，或者其他异步栈，就需要基于它做调整，而不是照搬。

它比普通提示词强在哪里？

普通提示词通常只会要求“Supabase 集成”，结果容易产出模糊或者混杂的架构。supabase-python 技能会把 Supabase 的认证/存储和 Python 数据建模分得更清楚，而这往往才是落地时最容易卡住的地方。

我一定要用 SQLModel 吗？

不一定，但这个技能本身就是围绕 SQLAlchemy/SQLModel 的类型安全数据库访问来设计的。如果你已经在用原生 SQL 或其他 ORM，这个技能在概念层面仍然有帮助，只是部分实现细节不会完全直接迁移。

它适合新手吗？

如果你已经掌握了基础 Python 和 FastAPI，它对新手是友好的。它不是 Supabase 或 SQLModel 的完整教程，所以新手需要自己补充一些项目上下文，并准备好把生成代码和现有应用结构对照检查。

如何改进 supabase-python 技能

先说清楚数据该放在哪里

最好的结果来自把需求拆成认证、关系型数据和文件存储三部分。比如明确写出：“Supabase 负责登录和头像上传；SQLModel 存 posts、comments 和 permissions。”这样可以避免 supabase-python 技能在数据存放位置上做出错误默认。

提前给出 schema 和路由意图

如果你想要的是能直接用的后端代码，第一轮提示里就要包含模型名称、关键字段和路由行为。像“User 有 id、email、role；创建 /auth/callback 和 /users/me 接口；强制基于角色的访问控制”就比泛泛要求集成要具体得多，也更可执行。

注意最常见的失败模式

最常见的问题，是把本该通过数据库层查询的数据过度交给 Supabase client 调用。如果第一版输出在模型定义或依赖注入方面显得太薄，就要求它改成以 SQLAlchemy/SQLModel 负责持久化、只把 Supabase 留给认证/存储/realtime。

结合项目约束迭代

如果你已经有现成的 migrations、环境变量约定，或者异步 session 模式，一定要在第二轮之前说明。supabase-python 技能越能贴合你当前的代码库，而不是另起炉灶，效果通常越好——尤其是在后端开发里，集成细节往往比示例代码更重要。