首页 / 开发手册 / 内容对外接口

内容对外接口

给小程序、APP 与前端框架调用的 HTTP 接口,参数与模板标签保持一致。

基本约定

项说明
前缀/api/open/v1(注意不是 /api/v1,那个地址被服务器组件保留)
返回格式{"code":0,"msg":"ok","data":…},code=0 表示成功
编码UTF-8
鉴权读取类接口默认开放;写入类接口需请求头 X-App-Key
限流默认每 IP 每分钟 120 次,可在调整
接口和模板用同一套取数逻辑。里能看到什么,接口就能取到什么; 模板标签支持哪些筛选参数,接口就支持哪些。不存在"页面能筛、接口不能"的两套规则。

接口一览

方法地址说明
GET/api/open/v1/site站点信息(名称、Logo、联系方式等)
GET/api/open/v1/navs导航树(含子栏目)
GET/api/open/v1/categories全部栏目
GET/api/open/v1/category/<ID或别名>单个栏目
GET/api/open/v1/contents内容列表(支持全部筛选参数)
GET/api/open/v1/content/<ID或别名>内容页(含正文、标签、关联)
GET/api/open/v1/tags标签列表
GET/api/open/v1/banners轮播图
GET/api/open/v1/links友情链接
GET/api/open/v1/docs手册目录 / 单篇
POST/api/open/v1/form/<表单标识>提交表单(需 AppKey)

内容列表的参数

参数说明
name / cid按栏目别名或 ID
model按内容模型过滤
num / page每页条数与页码
ordersort desc / publish desc / hits desc / id desc
keyword标题与摘要关键词
tag按标签名
withsub为 1 时连子栏目与副栏目一起取
media为 1 时同时返回图集
field / op / fvalue按自定义字段筛选,如 field=price&op=gt&fvalue=1000

内容响应里的访问门槛字段

内容被设了门槛(会员等级或仅登录)而当前请求没达标时, 接口不会把正文发出去 —— 它跟网页内容页用的是同一个判据(Member::gate())。 响应里会多出这几个字段,消费方靠它们决定显示什么:

字段说明
locked'1' = 这篇要门槛而没达标,content 与 gallery 已被摘掉
need_login'1' = 仅登录可见,不要求等级
need_level / need_level_name要求哪一档等级('0' = 不要求),以及那一档的名字
lock_why一句已经写好的说明,可直接显示给用户(会区分"没登录 / 不是会员 / 会员已过期 / 等级不够")

⚠️ 不要用"content 是不是空"来判断有没有被锁: 正文真的为空的内容,与被锁住的内容,在 JSON 里长得一模一样。 判断请只看 locked。

⚠️ 接口本身是公开访问,没有会员身份的概念, 所以带门槛的内容对匿名请求一律摘掉正文(fail closed)。 宁可让小程序少显示一点,也不能让它替站长把会员内容泄露出去。

调用示例

# 取「新闻」栏目最新 5 条
curl "https://你的域名/api/open/v1/contents?name=news&num=5&order=publish%20desc"

# 取价格高于 1000 的产品
curl "https://你的域名/api/open/v1/contents?model=product&field=price&op=gt&fvalue=1000"

# 取内容页
curl "https://你的域名/api/open/v1/content/12"

# 提交表单(需 AppKey)
curl -X POST "https://你的域名/api/open/v1/form/consult" \
     -H "X-App-Key: 你的AppKey" \
     -d "name=张三&phone=13800000000&need=想了解方案"

返回结构(内容列表)

{
  "code": 0,
  "msg": "ok",
  "data": {
    "total": 42,
    "page": 1,
    "pages": 5,
    "num": 10,
    "list": [
      {
        "id": 12,
        "cid": 3,
        "model": "article",
        "title": "标题",
        "url": "https://你的域名/detail/12",
        "summary": "摘要…",
        "thumb": "https://你的域名/uploads/…",
        "hits": 128,
        "publish_time": "2026-10-04 12:00:00",
        "ext": { "source": "本站" }
      }
    ]
  }
}

跨域

默认不发送任何跨域响应头,也就是只允许同源页面调用。 H5 页面部署在别的域名时,在「站点设置 → 内容输出接口」里把来源填进白名单即可,多个用逗号分隔。

不要图省事填 *:那等于允许任意网站拿着你访客的浏览器去调你的接口。

关于绝对地址

接口返回的图片与链接都是绝对地址。小程序和 APP 没有"当前页面"的概念, 相对路径拿去没法直接用 —— 这是接口与模板在这一点上刻意不同的地方。

没找到答案? 可以在 联系我们 留言说明使用场景,我们会补充进文档。