Hook 与服务挂载

import { Federation } from "@downcity/city";
import {
  AccountsService,
  BalanceService,
  PaymentService,
  googleAccountsProvider,
  stripePaymentProvider,
  UsageService,
} from "@downcity/services";

const base = new Federation({ db });
const balance = new BalanceService();

base.use(new AccountsService({
  token_ttl: "7d",
  providers: [
    googleAccountsProvider(),
  ],
}));

base.use(balance);
base.use(new PaymentService({
  readTopup: async (topup_id) => await balance.readTopup(topup_id),
  finishTopup: async (topup_id, extra) => await balance.finishTopup(topup_id, extra),
  providers: [
    stripePaymentProvider({
      secret_key: process.env.STRIPE_SECRET_KEY,
      webhook_secret: process.env.STRIPE_WEBHOOK_SECRET,
    }),
  ],
}));
base.use(new UsageService({
  record_errors: true,
}));

这段代码背后的意思是：

new AccountsService() 给 City 增加 accounts service 容器
AccountsService 会自动挂载 /providers、统一登录入口、me、管理侧读取、better-auth passthrough 与 OAuth callback 入口；具体登录方式只有在对应 provider 挂载且配置满足后才会开放
new PaymentService() 给 City 增加统一支付入口，用来暴露当前可用的支付方式
new UsageService() 给 City 增加 usage 记录能力和相关查询入口
stripePaymentProvider() 给统一 Payment 服务增加 Stripe Checkout、webhook 和支付结果同步

service 挂进来后产品端怎么调

从产品视角看，service 最终会变成统一 service：

const login = await guest.service("accounts").action("login/start").invoke({
  provider: "email",
  city_id: "city_demo",
});

await guest.service("accounts").action("login/continue").invoke({
  login_id: login.login_id,
  input: {
    email: "[email protected]",
    password: "password123",
  },
});

const session = await guest.service("accounts").get("login/result", {
  login_id: login.login_id,
});

const usage = await admin.service("usage").get("summary");

const methods = await guest.service("payment").get("methods");

const checkout = await user.service("payment").action("checkout/create").invoke({
  method_id: "stripe",
  topup_id: "topup_demo",
});

也就是说，service 并不会让产品端学第二套调用协议。

hook、service 的关系

可以把它们想成一条链：

service / action
  -> hook 在调用前后加规则
  -> service 提供可复用 service、表和管理能力
  -> client 统一通过 /v1/* 调用

这条链的好处是：

业务能力能复用
规则能集中治理
前端和后端的调用模型保持统一

常用 API / 入口

这一页最常用的公共入口其实很简单：

base.use(service)：把 service 挂进 City
guest.service("accounts")...
guest.service("payment").get("methods")
user.service("usage")...
admin.service("payment").get("payments")

如果你是从扩展角度思考，最重要的不是记很多 API，而是先判断“这是 hook 问题还是 service 问题”。

常见误解

service 不是单纯的 npm 包

它代表的是一整组进入 City 的能力边界，通常还伴随：

service
数据表
管理接口
可选 hook 逻辑

hook 不等于随便加中间件

hook 适合放横切治理逻辑，不适合把整个业务动作都塞进去。

service 不替代 City

service 负责把能力挂进 City，真正的产品调用入口仍然是 @downcity/city。

继续阅读

想看 city 端怎么统一调用 service，读 @downcity/city
想看账号能力，读 @downcity/services
想看 usage 记录，读 @downcity/services
想看 Stripe 一次性充值，读 @downcity/services

目录