mcpField
I
integration-fastapi

integration-fastapi

github.com/posthog数据与数据库7693 次安装今天更新
代码仓库

关于 integration-fastapi

用于在 FastAPI 应用中集成 PostHog 分析的技能。分步流程包含 Python 专属配置指导，涵盖事件发送、用户识别和异常跟踪。

主要功能

  1. 01四步集成流程
  2. 02FastAPI 与 Python 参考资料
  3. 03启动与关闭配置指导
  4. 04用户识别指导
  5. 05异常跟踪指导
  6. 06PII 处理指导

适用场景

  1. 01为 FastAPI 应用接入 PostHog
  2. 02在关闭时刷新分析事件
  3. 03在登录和注册时识别用户
  4. 04跟踪异常且不在事件中加入 PII

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/posthog/skills --skill integration-fastapi

安装后在 Claude Code 中输入/integration-fastapi确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/
basic-integration-1.0-begin.md
basic-integration-1.1-edit.md
basic-integration-1.2-revise.md
basic-integration-1.3-conclude.md
EXAMPLE.md
identify-users.md
python.md

详细介绍

FastAPI 的 PostHog 集成

此技能可帮助你将 PostHog 分析功能添加到 FastAPI 应用程序中。

工作流

按顺序完成集成：

  1. basic-integration-1.0-begin.md - PostHog 设置 - 开始 ← 从这里开始
  2. basic-integration-1.1-edit.md - PostHog 设置 - 编辑
  3. basic-integration-1.2-revise.md - PostHog 设置 - 修订
  4. basic-integration-1.3-conclude.md - PostHog 设置 - 总结

参考文件

  • references/EXAMPLE.md - FastAPI 示例项目代码
  • references/python.md - Python - 文档
  • references/identify-users.md - 用户识别 - 文档
  • references/basic-integration-1.0-begin.md - PostHog 设置 - 开始
  • references/basic-integration-1.1-edit.md - PostHog 设置 - 编辑
  • references/basic-integration-1.2-revise.md - PostHog 设置 - 修订
  • references/basic-integration-1.3-conclude.md - PostHog 设置 - 总结

示例项目展示了目标实现模式。请查阅文档了解 API 详情。

核心原则

  • 环境变量：始终使用环境变量存储 PostHog 密钥。切勿将其硬编码。
  • 尽量少改动：在现有集成旁添加 PostHog 代码。不要替换或重构现有代码。
  • 遵循示例：实现应尽可能遵循示例项目中的模式。

框架指南

  • 在应用启动时，使用 posthog.api_key 和 posthog.host 在 lifespan 上下文管理器中初始化 PostHog
  • 在 lifespan 关闭时调用 posthog.flush()，确保应用退出前发送所有事件
  • 使用带有 @lru_cache 装饰器的 Pydantic Settings 来缓存 get_settings()，并方便在测试中覆盖设置
  • 使用 FastAPI 依赖注入（Depends）在路由处理程序中访问 current_user 和 settings
  • 使用与 Flask/Django 相同的上下文 API 模式（依次使用 new_context()、identify_context(user_id)，然后调用 capture()）
  • 请记住，源代码位于 venv/site-packages 目录中
  • posthog 是 Python SDK 的软件包名称
  • 使用 pip install posthog 或 pip install -r requirements.txt 安装依赖项，切勿在 shell 命令中直接使用未加引号的版本说明符，例如 >=
  • 在 CLI 和脚本中：必须在退出前调用 posthog.shutdown()，否则所有事件都会丢失
  • 始终使用 Posthog() 类构造函数（基于实例的 API），而非模块级别的 posthog.api_key 配置
  • 始终在 Posthog() 构造函数中添加 enable_exception_autocapture=True，以自动跟踪异常
  • 绝不要在 capture() 事件属性中发送 PII——包括电子邮件、全名、电话号码、实际地址、IP 地址或用户生成的内容
  • PII 应放在 identify() 人员属性中，而非 capture() 事件属性中。安全的事件属性是 message_length、form_type、布尔标记等元数据。
  • 使用 atexit.register() 注册 posthog_client.shutdown，确保退出时刷新所有事件
  • Python SDK 没有 identify() 方法——请使用 posthog_client.set(distinct_id=user_id, properties={...}) 设置人员属性，或在上下文中使用 identify_context(user_id)

识别用户

在登录和注册事件期间识别用户。请参阅示例代码和文档，了解此框架的正确识别模式。如果同时存在前端和后端代码，请使用 X-POSTHOG-DISTINCT-ID 和 X-POSTHOG-SESSION-ID 标头传递客户端会话和 distinct ID，以保持关联。

错误跟踪

在相关文件中添加 PostHog 错误跟踪，尤其是关键用户流程和 API 边界附近。

评论

支持 Markdown