本文作者:icy

daraja-restful:用 Pascal 优雅对接 M-Pesa Daraja API

icy 昨天 27 抢沙发
daraja-restful:用 Pascal 优雅对接 M-Pesa Daraja API摘要: daraja-restful:用 Pascal 优雅对接 M-Pesa Daraja API 项目地址:https://github.com/michaelJustin/daraj...

daraja-restful:用 Pascal 优雅对接 M-Pesa Daraja API

daraja-restful:用 Pascal 优雅对接 M-Pesa Daraja API

项目地址:https://github.com/michaelJustin/daraja-restful

一、这是什么

daraja-restful 是一个使用 Free Pascal / Delphi 编写的小型 RESTful 客户端库,用于对接 Safaricom M-Pesa Daraja API。Daraja 是肯尼亚电信运营商 Safaricom 提供的移动支付开放平台,开发者可以通过它实现手机钱包收款、支付、查询交易状态、退款、账单校验等能力。

在 PHP、Node.js、Python、Java 社区里,针对 Daraja 的 SDK 一抓一大把;但在 Pascal 世界,这类现成的封装几乎没有。daraja-restful 就是为了填补这个空白而诞生的——它让长期使用 Object Pascal 做后端(尤其是一些非洲本地企业仍在大量使用 Delphi/FPC 构建系统)的开发者,不必再为了接一次 M-Pesa 就临时装上另一种语言运行时。

项目规模很小,代码风格朴素直接,定位是”够用的封装“而不是”全功能框架”。适合拿来即用,也适合作为一个学习 Pascal 调用现代 REST API 的参考样本。


二、它解决了什么问题

直接调用 Daraja API 并不是”发个 HTTP 请求”那么简单,真实接入时有几个门槛:

  1. OAuth 认证:Daraja 使用 OAuth 2.0,需要先用 Consumer Key + Consumer Secret 换取 Bearer Token,且 Token 有有效期(通常 1 小时),过期要重新获取。
  2. Basic Auth 构造:换取 Token 的请求本身需要把 Consumer Key/Secret 拼接后做 Base64 编码并放入 Authorization: Basic ... 头。
  3. 请求体格式:几乎所有业务接口(STK Push、C2B、B2C、查询等)都要求 JSON body,且字段命名、大小写、必填项都很挑剔。
  4. 响应解析:返回的是 JSON,需要按字段取值并做错误判断(ResponseCode、errorCode、errorMessage 等)。
  5. 加签:部分接口(如 C2B 的 URL 注册、部分安全接口)需要 RSA 或特定签名。

这些重复劳动如果每接一个项目都手写一遍,很快就会出现样板代码泛滥。daraja-restful 把这些套路收敛到一组 Pascal 单元里,让你用几行代码完成一次支付发起或状态查询。


三、它大概长什么样

说明:以下为对项目典型用法的说明性示例,具体类名/方法签名请以实现为准。阅读源码时以 daraja-restful 仓库中的单元(.pas)文件为准。

一个典型的调用流程大致是:

Pascal
uses
  daraja_client, daraja_types, fpjson;

var
  Client: TDarajaClient;
  Resp  : TJSONObject;
begin
  Client := TDarajaClient.Create;
  try
    // 1. 配置环境凭证
    Client.Environment   := deSandbox;   // 沙箱 / 生产
    Client.ConsumerKey   := 'your-consumer-key';
    Client.ConsumerSecret:= 'your-consumer-secret';
    Client.ShortCode     := '174379';
    Client.PassKey       := 'your-lipa-na-mpesa-passkey';
    Client.CallbackURL   := 'https://example.com/mpesa/callback';

    // 2. 获取 OAuth Token(内部会缓存)
    Client.Auth;

    // 3. 发起 STK Push(Lipa na M-Pesa Online)
    Resp := Client.StkPush(
      '254712345678',   // 手机号(国际格式,不带 +)
      100,              // 金额,以 KES 为单位
      'INV-0001',       // AccountReference
      'Payment for order 0001'  // TransactionDesc
    );
    try
      WriteLn('CheckoutRequestID = ', Resp.Get('CheckoutRequestID', ''));
    finally
      Resp.Free;
    end;
  finally
    Client.Free;
  end;
end;

关键点:

  • Auth 方法封装了 OAuth 换取 Token 的全过程,包括 Basic Auth 头的构造和返回 JSON 里 access_token 的提取,通常还会把这个 token 缓存在客户端实例上,避免每次都去换。
  • 业务方法返回 TJSONObject,把解析的主动权交给调用方,这一点很符合 Pascal 生态里 fpjson/SuperObject 的惯用法——库不替你定义一大堆 DTO 类型,你按需取字段。
  • Environment 切换沙箱/生产,Daraja 的沙箱和生产 base URL 是固定的两条,把它做成枚举避免手写 URL 出错。
  • Callback URL 由业务侧提供,库本身是”发起端”,异步回调的处理要由你自己的 Web 服务(比如 fpweb、mORMot、Delphi Datasnap 等)去接收。

四、技术栈与依赖

从项目性质来看,它依赖的是 Pascal 生态里最常见的两件工具:

  • HTTP 客户端:fphttpclient(Free Pascal)或 RESTRequest / TIdHTTP(Delphi 侧),负责发 HTTPS 请求、设置 header、读响应体。
  • JSON 处理:fpjson + jsonparser(FPC 自带)或项目自己选定的 JSON 库。

这意味着它不需要第三方商业组件,用 LTS 版 FPC 或较新版本 Delphi 拉下来就能编译,可移植性不错。如果你的项目已经在用 Lazarus 或做了跨 FPC/Delphi 兼容,这个库几乎零接入成本。


五、设计取向与权衡

这个小项目有几个比较”务实”的设计取向,值得点出来:

1. 不做过度抽象。 没有为了”接口即一切”而设计大量抽象类,也没有自己搞一套 HTTP 层。业务逻辑直接落在 JSON 之上,读起来一目了然。代价是类型安全性弱一些——字段名写错要运行时才暴露。

2. 把 OAuth 生命周期管起来。 Token 过期是 Daraja 接入最常见的踩坑点,把”取 token”和”用 token”合并在客户端对象里,比每次请求前都手动换 token 要省心得多。

3. 回调是”责任边界”。 Daraja 的 STK Push 是异步的:你调用一次,用户手机上弹出支付框,支付结果通过 CallbackURL 以 POST 的形式推回来。这个回调需要你自己的 Web 服务去响应、验签、入库。daraja-restful 只负责”发出去”,”接回来”留给你——这是合理的职责划分,因为回调的处理策略高度依赖业务系统。

4. 沙箱友好。 有沙箱环境是 Daraja 的一大优势,库显式区分环境,能让开发者在正式接入前把整条链路跑通。


六、典型使用场景

  • Pascal 后端项目接 M-Pesa:用 Delphi/FPC 写的 ERP、POS、订单系统想直接支持手机支付,daraja-restful 让你不必再引入一个 Node/PHP 中间层。
  • 桌面/嵌入式 POS 写 M-Pesa 支付:在收银终端上直接发起 STK Push,弹出付款框,异步回调在收银服端接收。
  • 作为学习样本:想学 Pascal 怎么优雅地调用现代 REST API(OAuth、Basic Auth、JSON 请求/响应、错误处理),这个库代码量不大,通读一遍能覆盖大部分模式。

七、需要注意的地方

  • 本项目体量较小、属于个人开源项目,生产接入前建议通读源码,确认对错误处理、超时、重试、并发 token 刷新的处理是否满足你的场景。
  • 敏感凭证不要写死在代码里,Consumer Secret、PassKey 一旦泄露等同于账户被接管;应当从环境变量或加密配置中读取。
  • HTTPS 与回调验签:生产环境必须使用 HTTPS 回调,并在回调处理端校验来源与字段,防止伪造支付通知。
  • Daraja 的字段与文案会变:Safaricom 对 Daraja 做过多次版本迭代(例如发票单价、描述字段的必填性、响应码枚举等),接入时以官方文档当前版本为准,别完全依赖第三方库的默认值。

八、总结

daraja-restful 的价值不在于”功能多”,而在于它填上了 Pascal 生态和 M-Pesa 支付之间那块缺失的拼图。它遵循 Pascal 社区偏爱的简洁直白风格,把 OAuth、HTTP、JSON 这些重复性的胶水代码封装成一组小而清晰的单元,让 Free Pascal / Delphi 项目能以最少的额外依赖接入肯尼亚最主流的移动支付渠道。

如果你正用 Object Pascal 做后端,又恰好需要支持 M-Pesa,那么值得先把它拉下来读一读——无论最终直接用它,还是照它的思路自己封装一层,这份”在 Pascal 里调 REST API”的经验都能复用。

daraja-restful_20250720114446.zip
类型:压缩文件|已下载:0|下载方式:免费下载
立即下载
文章版权及转载声明

作者:icy本文地址:https://zelig.cn/delphi/1505.html发布于 昨天
文章转载或复制请以超链接形式并注明出处软角落-SoftNook

觉得文章有用就打赏一下文章作者

支付宝扫一扫打赏

微信扫一扫打赏

阅读
分享

发表评论

快捷回复:

评论列表 (暂无评论,27人围观)参与讨论

还没有评论,来说两句吧...