在 Encore.ts 中集成 Polar支付、订阅与许可证密钥的完整接入指南【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encorePolar 作为你的 Merchant of Record记录商户一站式处理支付、订阅与许可证密钥等商业化核心环节。本文将基于 Encore 开源仓库中的官方集成文档完整演示如何在 Encore.ts 应用中接入 Polar从 SDK 安装、Polar 后台配置、密钥管理、Checkout 会话创建到 Webhook 事件处理与最终部署并深入源码层讲解secret()、api.raw、ENCORE_ENVIRONMENT等 Encore 运行时机制帮助你构建一套可上线的支付与订阅闭环。适用前提本指南面向 TypeScript 语言版本的 Encore 应用。若尚未安装 Encore请先参阅仓库内的 安装指南再继续后续步骤。快速开始从官方示例创建应用如果你希望跳过手工搭建、直接获得一份可运行的 Polar 集成范例可以使用 Encore CLI 基于官方示例模板创建新应用$ encore app create --examplets/polar该命令会拉取一个已经配置好 Polar 客户端、Checkout 端点与 Webhook 处理的完整 TypeScript 示例项目。也可以按照下文步骤把 Polar 逐步接入到已有的 Encore 应用中。安装 Polar SDK在 Encore.ts 项目根目录执行$ npm install polar-sh/sdkpolar-sh/sdk是 Polar 官方的 TypeScript/JavaScript SDK封装了 Checkout 会话创建、Webhook 校验、订单与订阅查询等能力后续所有 Polar 交互都通过它完成。Polar 后台配置编写代码之前需要先在 Polar 控制台完成三件事开发阶段请使用 sandbox 沙箱环境避免影响真实计费数据创建 Access Token访问令牌进入 Settings Developers Personal Access Tokens新建一个令牌用于服务端鉴权。创建商品Product进入 Products 页面创建至少一个商品并复制其product ID。后续创建 Checkout 会话时需要用它指定用户要购买的商品。配置 Webhook本地开发可延后进入 Settings Webhooks将回调地址指向你的 API 地址加上/webhooks/polar路径。本地开发时可使用 ngrok 之类的隧道工具把本地服务暴露到公网供 Polar 回调。关于商品定价、订阅计划与 Webhook 事件类型的更多细节可查阅 Polar 官方文档本指南只介绍与 Encore 集成直接相关的部分。用 Encore Secrets 保存 Polar 凭据Polar 的 Access Token 属于敏感凭据绝不能硬编码进源码。Encore 提供内置的密钥管理机制通过 CLI 设置$ encore secret set --type dev,local,pr,production PolarAccessToken--type指定该密钥生效的环境集合dev开发云、local本地、pr预览环境与production生产。Encore 会为每个环境独立加密存储环境之间互不共享。本地开发时密钥直接保存在你的机器上并在运行encore run时自动注入到应用中——无需任何.env文件也避免了.env文件被误提交进 Git 仓库的风险。在源码中通过 Encore 的secret()函数读取密钥。以仓库中 runtimes/js/encore.dev/config/secrets.ts 的实现为例secret(name)从运行时配置中获取该密钥的实现返回一个可调用对象本地开发runtime.CloudProvider.Local且密钥未设置时它会返回空字符串而不是直接抛错方便调试而在非本地环境中若密钥缺失会抛出secret name is not set错误。此外该对象重写了toString()输出为Secretname(*********)确保日志中不会泄露明文。密钥值会被 Encore 周期性刷新这意味着它可以安全轮换而无需重启服务。初始化 Polar 客户端新建polar.ts用 Encore 的secret()读取令牌并根据运行环境在 Polar 的sandbox沙箱与production生产服务器之间切换-- polar.ts -- import { Polar } from polar-sh/sdk; import { secret } from encore.dev/config; const polarAccessToken secret(PolarAccessToken); const server process.env.ENCORE_ENVIRONMENT production ? production : sandbox; export const polar new Polar({ accessToken: polarAccessToken(), server, });这里的ENCORE_ENVIRONMENT是 Encore 注入的环境变量在生产环境部署时其值为production其余情况本地、预览、测试等走 sandbox从而保证开发与生产天然隔离。如果你需要更结构化的环境信息Encore 还提供appMeta()API见 runtimes/js/encore.dev/app_meta.ts可读取environment.type、environment.cloud、apiBaseUrl等元数据。创建 Checkout 会话Checkout 会话是用户完成支付的关键入口。下面通过一个需要认证的 Encore 端点创建 Checkout 会话并返回支付跳转链接-- checkout.ts -- import { api } from encore.dev/api; import { polar } from ./polar; import { getAuthData } from ~encore/auth; interface CreateCheckoutRequest { productId: string; } interface CreateCheckoutResponse { checkoutUrl: string; } export const createCheckout api( { auth: true, expose: true, method: POST, path: /checkout }, async (req: CreateCheckoutRequest): PromiseCreateCheckoutResponse { const authData getAuthData()!; const baseUrl process.env.ENCORE_API_URL || http://localhost:4000; const session await polar.checkouts.create({ products: [req.productId], customerEmail: authData.email, successUrl: ${baseUrl}/?successtrue, }); return { checkoutUrl: session.url || }; } );对这段代码的要点拆解auth: true与getAuthData()auth: true声明该端点必须携带有效认证信息否则 Encore 直接返回 401。认证数据通过~encore/auth的getAuthData()获取内部实现在 runtimes/js/encore.dev/internal/auth/mod.ts从当前请求上下文中取出认证数据因此可以把用户的邮箱直接传给 Polar 作为customerEmail实现登录即下单的体验。expose: true把端点暴露到公网使其可以被前端调用。未设置expose的端点默认只在服务内部网络可达。path: /checkout自定义路由路径。Encore 的api()声明在 runtimes/js/encore.dev/api/mod.ts 中支持method、path、expose、auth、bodyLimit、sensitive等选项路径中还可使用:id单段参数与*path通配多段参数。ENCORE_API_URLEncore 注入的当前环境 API 基地址。本地开发时通常是http://localhost:4000部署后则是对应环境的 API URL。这里用其拼接successUrl保证用户在 Polar 完成支付后能正确跳回你的应用。polar.checkouts.create()返回的session.url即用户在 Polar 侧完成支付的 Checkout 页面链接前端拿到后直接跳转即可。处理 Webhook让支付事件驱动业务支付是异步过程用户可能在 Polar 侧完成支付或取消订阅这些状态变化通过Webhook通知你的服务。Encore 的raw endpoint原生端点让你直接拿到 Node.js 风格的IncomingMessage请求对象非常适合承接 Webhook 这类需要原始请求体的场景-- webhooks.ts -- import { api } from encore.dev/api; import log from encore.dev/log; export const handleWebhook api.raw( { expose: true, path: /webhooks/polar, method: POST }, async (req, res) { const chunks: Buffer[] []; for await (const chunk of req) { chunks.push(chunk); } const event JSON.parse(Buffer.concat(chunks).toString()); log.info(Received Polar webhook, { type: event.type }); switch (event.type) { case subscription.active: // Grant access to your product break; case subscription.canceled: // Revoke access break; case order.paid: // Fulfill the order break; } res.writeHead(200); res.end(); } );api.rawEncore 提供的原生端点声明。req是stream.Readable类型的请求对象实现在 runtimes/js/encore.dev/api/node_http.ts可以用异步迭代器逐块读取请求体res是ServerResponse兼容的响应对象同一文件 L115-L310支持writeHead、write、end等标准操作。由于完全兼容 Node.js HTTP 语义它可以无缝对接 Express 等生态库。事件分发示例按event.type分派三类典型事件——subscription.active订阅激活授予产品访问权限、subscription.canceled订阅取消收回权限、order.paid订单支付成功履行订单。你可以在switch中补充实际的业务逻辑例如调用数据库 API 更新用户权益或给用户发放许可证密钥。确认响应处理完成后返回 200告知 Polar 事件已收到避免 Polar 重复投递。注册 Webhook 时在 Polar 控制台的 Settings Webhooks 中填写你的 Encore API URL 加/webhooks/polar并勾选需要监听的事件如subscription.active、subscription.canceled、order.paid。建议生产环境务必校验 Webhook 请求的签名Polar SDK 提供相应工具并配合数据库做幂等处理防止重复事件导致权益重复发放。部署当通过 Encore 部署应用时Encore 会自动为应用提供并管理所需的全部基础设施Secrets密钥按环境preview、staging、production独立加密存储环境之间绝不共享。Databases数据库在 GCP 上自动预置为 Cloud SQL在 AWS 上自动预置为 RDS。Networking网络包含 TLS 证书、负载均衡与 DNS 解析开箱即用。自托管部署如果你希望把应用部署到自有基础设施可以构建 Docker 镜像$ encore build docker my-app:latest构建产物是一个标准 Docker 镜像可部署到任何支持 Docker 的环境。更详细的自托管说明见仓库内的 self-host 文档。Encore Cloud也可以直接推送到 Encore 的开发云获得一个免费的 staging 环境$ git push encore main如果你想部署到自己的 AWS 或 GCP 账号连接云账号后Encore 会自动预置基础设施并代为管理密钥。具体步骤参考 连接云账号指南。小结把 Polar 与 Encore.ts 集成本质上是三个动作的组合用 Encore Secrets 安全托管 Polar Access Token、用类型安全的api()端点创建 Checkout 会话、用api.raw原生端点接收 Webhook 事件并驱动业务。Polar 承担了商户记录、支付合规、订阅计费与许可证发放等重活Encore 则负责运行时配置、密钥注入、环境区分与一键部署二者互补后你得到的是一套具备生产级基础设施的支付订阅能力。仓库内的encore app create --examplets/polar示例是快速上手的最佳起点可直接在此基础上扩展你自己的业务逻辑。【免费下载链接】encoreThe infrastructure platform for the intelligence era项目地址: https://gitcode.com/GitHub_Trending/encor/encore创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
