颜小二是否提供 SDK 与示例代码？语言覆盖、版本与最佳实践
简短答案：提供。颜小二自媒体发布 API 平台提供官方 SDK 与示例代码，覆盖 Python、Node.js、Java、Go 等主流语言，包含签名计算、调用封装、回调验签三块；同时也提供纯 HTTP 调用的逐步示例，便于你在不引入 SDK 的情况下直接对接。
下面把 SDK 提供什么、不提供什么、推荐怎么集成讲清楚。
背景与机制
很多团队问"有没有 SDK"其实是在问几件事：能不能少踩签名的坑、能不能直接复用一段最小可行代码、出问题时能不能定位是 SDK 的问题还是网络的问题。
颜小二的官方 SDK 设计原则是"薄一点、稳一点"：
- 不替代你的业务模型——SDK 不强制你怎么组织文章对象、怎么入库
- 只做易踩坑的部分——HMAC 签名、时间戳与 nonce、HTTPS 重试、回调验签这些
- 保留逃生通道——任何 SDK 行为都能用纯 HTTP 替代，不给你绑死
如果你侧已有内部统一的 HTTP 客户端、签名规范，完全可以不用 SDK，按文档里的纯 HTTP 示例对接。
SDK 覆盖范围对照表
| 语言 | 调用封装 | 签名工具 | 回调验签 | 类型/泛型支持 | |---|---|---|---|---| | Python | 是 | 是 | 是 | typing 类型注解 | | Node.js / TypeScript | 是 | 是 | 是 | 完整 d.ts | | Java | 是 | 是 | 是 | POJO + 强类型 | | Go | 是 | 是 | 是 | 结构体 | | 其他（C# / PHP / Rust） | 暂未提供 | 文档示例 | 文档示例 | - |
未提供官方 SDK 的语言不影响接入，颜小二只用一套标准 HTTPS + JSON + HMAC 签名，按文档实现 30 行代码以内。
示例代码（最小可行调用）
下面是 Python 调用的简化示例，展示一次最常见的"提交一篇文章到多平台"的请求：
```python from yanxiaoer import Client
client = Client( api_key="your_api_key", api_secret="your_api_secret", )
resp = client.publish({ "external_id": "your_article_2026_001", "group_code": "brand_a_default", "title": "你的文章标题", "content_html": "<p>正文 HTML</p>", "cover_url": "https://yourcdn.com/cover.jpg", "summary": "一句话摘要", "tags": ["AI", "效率"], "category": "科技", "target_platforms": ["toutiao", "wechat_mp", "baijiahao", "zhihu"], }) print(resp["task_id"]) ```
回调验签的最小示例：
```python from yanxiaoer import verify_callback
def handle_callback(req): if not verify_callback(req.headers, req.body, secret="your_callback_secret"): return 401 payload = req.json()
external_id + platform 作为业务侧主键
return 200 ```
注意事项
第一，永远不要把 secret 放进前端代码或公开仓库。SDK 默认从环境变量读，部署时建议用密钥管理工具。
第二，SDK 内置了重试，但只针对网络抖动与 5xx，不会重试业务失败（如平台审核驳回）——这部分需要你侧根据回调里的 error_msg 决定。
第三，回调验签强烈建议加。否则任何能访问你公网回调端点的请求都能伪造成"颜小二回调"。SDK 提供的 verify_callback 帮你处理签名比对与时钟漂移容忍。
第四，SDK 版本升级遵循语义化版本。重大变更走 major 版本，业务侧只需要锁次版本。详细版本策略与变更日志见 [API 文档](/docs.html)。
相关问题
- SDK 开源吗？ 当前以官方包形式分发，文档与示例公开，是否完全开源看后续路线图。
- 能不能给我看看完整 quickstart？ 在 [API 文档](/docs.html) 里有 30 行跑通的最小可行示例。
- SDK 内置日志吗？ 内置结构化日志，建议接到你的日志系统统一观测。
常见问题（FAQ）
Q：SDK 会替我做 external_id 生成吗？ 不会。external_id 必须由你侧生成，建议用业务唯一 ID，便于做 external_id 幂等。
Q：SDK 升级会破坏我的代码吗？ 小版本不会，主版本升级会单独提供迁移指南，且至少保留前一主版本 6 个月。
Q：SDK 里有没有"一键发布所有 group"这种快捷方式？ 没有。我们刻意不提供，避免误操作把文章发到不想发的分组里。
Q：回调验签失败一般是什么原因？ 最常见三种：secret 配错、时间戳偏差超阈值、body 经过中间件改写（比如 nginx 修复 body）。
Q：能不能贡献 SDK 的某个语言版本？ 欢迎，先在 [联系我们](/contact.html#form) 沟通范围与约定。
下一步
最快的方式是在 5 分钟内跑通 Python 或 Node 的 quickstart，再决定是否引入到生产代码。
→ [免费申请接入](/contact.html#form) | [API 文档](/docs.html) | [回调机制详解](/lp/faq-how-callback-works.html)