客户端库

LinkProfit 官方的 Node、Python 和 PHP 客户端库：重试、幂等和分页遵循同一套约定，另附各语言的快速上手示例。

更新于 2026年8月14日

REST API 就是普通的 HTTP 和 JSON，用一个 fetch 调用去访问它完全够用。客户端库存在的意义，在于那些没人愿意写第二遍的部分：正确地重试一个被限流的请求、让重试的创建操作保持安全，以及顺着游标把一个列表翻到底。

三个库，一套约定：

| 语言 | 包名 | 源码位置 | | --- | --- | --- | | Node.js / TypeScript | @linkprofit/sdk | packages/sdk-node | | Python | linkprofit | sdk/python | | PHP | linkprofit/linkprofit-php | sdk/php |

安装

这些包还没有发布到 npm、PyPI 或 Packagist。 发布要等各个仓库账号就绪；代码本身已经完整，今天就可以从仓库的本地副本安装，而一旦账号到位，下面的命令就会变成一行 npm install @linkprofit/sdk（其他语言同理）。

Node，从本地副本安装：

npm install /path/to/linkprofit/packages/sdk-node

Python，从本地副本安装：

pip install /path/to/linkprofit/sdk/python

PHP，在 composer.json 中通过 Composer 的 path 仓库安装：

{
  "repositories": [
    { "type": "path", "path": "/path/to/linkprofit/sdk/php" }
  ],
  "require": {
    "linkprofit/linkprofit-php": "*"
  }
}

三个库一致的行为

这些库刻意写得平淡，也刻意写得彼此相像。行为只需要理解一次，在每种语言里都成立。

身份认证。 你传入一个工作区密钥（lp_live_…），客户端会在每个请求上设置 Authorization 请求头。基础 URL 是一个可选项，因此同一份代码在测试中可以指向本地实例。权限与轮换详见身份认证。

尊重服务端的重试。 429 和临时性的 5xx 会带退避地重试，Retry-After 会被遵循而不是靠猜——窗口何时释放，服务端本来就知道。尝试次数有上限，而那些本身就有问题的请求（validation_failed、conflict、not_found）绝不会被重试：重复发送一个错误的请求，只会白白消耗限流配额。

幂等的写操作。 每一次写调用都会带上 Idempotency-Key，因此网络超时后的重试返回的是已保存的响应，而不会再创建一条链接。当重试可能来自另一个进程或稍后的一次运行时，你也可以自己提供幂等键——订单 id、任务 id 都可以。幂等键会保存 24 小时；同一个幂等键搭配不同的请求体会返回 409。

把游标分页变成迭代器。 列表端点采用游标分页，客户端把它们暴露成迭代器：你直接遍历链接，当前一页取完时客户端自动取下一页，游标变为 null 时停止。不必自己算页码，也不会因为差一错误而悄悄漏掉一条记录。

错误即异常。 失败会抛出该语言中自然的错误类型，其中带有 API 的 code、给人看的消息，以及校验失败时逐字段的 details。请按错误码分支处理，而不是按消息文本——错误码才是写进文档的约定。

Node 客户端的请求与响应类型，由参考文档所渲染的同一份 OpenAPI 文档生成——该文档发布在 /openapi.json——因此类型不可能与线上运行的 API 产生偏差。Python 和 PHP 客户端则由人手对照同一份文档实现，各自采用本语言的惯用写法。

快速上手

每个包都附带一份 README，列出它的完整接口；下面的片段展示的是三个库共有的形态——用密钥构造客户端，调用对应的资源分组，拿回一个有类型的对象。

Node

import { LinkProfit } from "@linkprofit/sdk";

const client = new LinkProfit({ apiKey: process.env.LINKPROFIT_API_KEY });

const created = await client.createLink({
  url: "https://example.com/summer-sale",
  title: "Summer sale",
});

console.log(created.data.short_url);

Python

import os

from linkprofit import LinkProfit

client = LinkProfit(os.environ["LINKPROFIT_API_KEY"])

created = client.create_link(
    {"url": "https://example.com/summer-sale", "title": "Summer sale"}
)

print(created["data"]["short_url"])

PHP

<?php

require __DIR__ . '/vendor/autoload.php';

use LinkProfit\LinkProfit;

$client = new LinkProfit(getenv('LINKPROFIT_API_KEY'));

$created = $client->createLink([
    'url' => 'https://example.com/summer-sale',
    'title' => 'Summer sale',
]);

echo $created['data']['short_url'];

我该用哪一个

Node / TypeScript —— 接口最完整，因为它的类型直接来自 OpenAPI 文档。JavaScript 后端、serverless 函数或构建脚本的自然之选。
Python —— 用于报表和数据工作：把分析数据拉进 notebook、定时任务或某个看板的数据源。
PHP —— 面向 CMS 那一侧的世界。比如一个 WordPress 插件，或者一个在内容发布时顺手缩短链接的 Laravel 服务。
一个都不用 —— 如果你的语言不在其中，API 本来就是普通的 HTTP。快速上手以 curl 为主，而这些库做的每一件事（重试、幂等、游标）都是写进文档的行为，五十行代码就能自己实现。

无论你选哪一个，API 参考都是端点、字段和错误码的完整清单——这些库只是它之上的便利封装，绝不是另一套 API。