Hook 与服务挂载

import { CityBase } from "@downcity/city";
import { accountsService } from "@downcity/services";
import { balanceService } from "@downcity/services";
import { paymentService } from "@downcity/services";
import { stripePaymentMethod } from "@downcity/services";
import { usageService } from "@downcity/services";
import { stripePaymentService } from "@downcity/services";

const base = new CityBase({ db });
const balance = balanceService();

base.use(accountsService({
  token_ttl: "7d",
}));

base.use(balance);
base.use(paymentService({
  methods: [
    stripePaymentMethod(),
  ],
}));
base.use(usageService({
  record_errors: true,
}));

base.use(stripePaymentService({
  balance: {
    readTopup: async (topup_id) => await balance.readTopup(topup_id),
    finishTopup: async (topup_id, extra) => await balance.finishTopup(topup_id, extra),
  },
  secret_key: process.env.STRIPE_SECRET_KEY,
  webhook_secret: process.env.STRIPE_WEBHOOK_SECRET,
}));

这段代码背后的意思是：

accountsService() 给 City 增加 accounts service
paymentService() 给 City 增加统一支付入口，用来暴露当前可用的支付方式
usageService() 给 City 增加 usage 记录能力和相关查询入口
stripePaymentService() 给 City 增加 Stripe Checkout、webhook 和支付结果同步

service 挂进来后产品端怎么调

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

const session = await guest.service("accounts").action("login").invoke({
  email: "user@example.com",
  password: "password123",
  town_id: "town_demo",
});

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

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

const checkout = await user.service("payment.stripe").action("checkout/create").invoke({
  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.stripe")...

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

常见误解

service 不是单纯的 npm 包

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

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

hook 不等于随便加中间件

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

service 不替代 City

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

继续阅读

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

目录