API 设计

资源 ID 放进 URL 路径通常符合 RESTful 习惯，但某些第三方平台会把每个真实 pathname 当成独立接口，导致访问量、错误率和耗时无法聚合。本文讨论在无法取得路由模板时，如何用固定低基数路径与查询参数重新平衡 API 语义和可观测性。

在 Hono 项目中同时使用 Zod 校验、RPC 类型客户端和 OpenAPI 时，最容易出现路由能运行、客户端能编译、文档却已经漂移。本文用普通 Hono 路由配合 hono-openapi，说明请求 Schema、响应类型、错误契约和接口说明各自应该放在哪里。

记录一次实时追加列表的分页设计：为什么 OFFSET 在新数据持续插入时会重复或漏项，怎样用自增 ID 作为 Keyset Cursor 稳定加载旧记录，以及如何用 pageSize + 1 判断 hasMore，避免额外 COUNT 和空页请求。

一次 Taro 前台分页改造记录：从用单页条数猜测是否还有下一页，到发现列表接口每次返回 total 会重复执行 COUNT，最后将列表与总数拆成两个接口，并按筛选条件缓存总数，减少空页请求和翻页开销，同时说明排序、搜索、缓存键和新旧客户端的发布顺序。