Bangumi Server 目录 API 教程从零创建你的专属条目合集【免费下载链接】serverAPI server for bgm.tv项目地址: https://gitcode.com/gh_mirrors/server17/serverBangumi Server 是 bgm.tv 的开源 API 服务端本文带新手从零上手它的目录 API一步步创建属于自己的条目合集。目录Index是 Bangumi 整理动画、书籍、游戏条目的核心功能通过 REST 接口即可完成创建、编辑、收藏全流程轻松搭建我的年度十佳动画补番计划清单这样的专属合集。全程无需掌握复杂技术跟着这篇入门教程就能快速跑通。 目录 API 是什么为什么要用它在 Bangumi 世界里目录就是一套用户自建的条目合集你可以把散落在动画、书籍、游戏、三次元各个分类下的条目按自己的主题收纳到同一个列表里。而 Bangumi Server 提供的目录 API让开发者可以用代码远程完成这一切——无论你是想做一个私人追番清单还是给社区贡献一份优质推荐合集都不需要手动在网页上一个个添加。整套目录功能的接口都集中在服务端路由文件 web/routes.go 中逻辑清晰、风格统一非常适合作为你学习这个项目的入门入口。 快速开始准备好你的认证凭证调用目录 API 前你只需要准备两样东西准备项说明服务地址自部署的 Bangumi Server仓库地址https://gitcode.com/gh_mirrors/server17/server OAuth Token登录后获取的访问令牌用于身份认证 注意创建、修改目录需要write_indices权限收藏目录需要write_collection权限请求头带上Authorization: Bearer token即可。✨ 第一步用目录 API 创建专属条目合集万事开头难但创建目录非常简单。向POST /v0/indices发送一个 JSON 请求体即可{ title: 我的年度十佳动画, description: 2026 年我最喜欢的十部动画持续更新中 }请求体只需title和description两个字段定义见 web/req/index.go。服务端处理逻辑在 web/handler/index/index.go校验文本、写入数据库然后立刻返回完整的目录对象。返回结果中包含了目录的id、total条目数、stat.collects收藏数等信息字段结构可以参考 web/res/index.go。拿到返回的id之后你的专属条目合集就诞生了 第二步把条目加入你的合集创建好目录下一步就是往里添加条目。调用POST /v0/indices/:id/subjects在 URL 路径中带上目录id请求体写明要加入的条目{ subject_id: 123456, sort: 1, comment: 神作强推 }subject_id条目的 ID必填sort排序权重数字越小越靠前可选comment你对这个条目的短评可选对应的实现位于 web/handler/index/subject.go添加前服务端会校验目录归属权确保只有创建者本人能修改。 第三步查询目录与条目列表想查看别人或自己的合集两个只读接口就够了GET /v0/indices/:id—— 获取目录的基本信息包括创建者、收藏数、简介等GET /v0/indices/:id/subjects—— 获取目录下的条目列表支持type参数按条目类型过滤如仅看动画也支持limit/offset分页值得一提的是公开目录的查询结果会被缓存一小时见 web/handler/index/index.go所以热门合集的高频访问非常高效。️ 进阶技巧排序、修改与删除调整条目的排序和评论调用PUT /v0/indices/:id/subjects/:subject_id重新提交sort和comment即可移除条目调用DELETE /v0/indices/:id/subjects/:subject_id一键删除修改目录本身调用PUT /v0/indices/:id更新标题与简介这三个写操作的权限校验逻辑统一封装在ensureIndexPermission函数里web/handler/index/index.go——只有目录的创建者才能修改其他用户会收到 401 响应安全省心。❤️ 收藏 API让好合集被更多人看到看到别人整理得很棒的合集想收藏起来收藏相关的目录 API也很简单POST /v0/indices/:id/collect—— 收藏目录DELETE /v0/indices/:id/collect—— 取消收藏实现位于 web/handler/index/collect.go服务端会先校验目录是否存在、是否对当前用户可见再执行收藏操作重复收藏会被安全地忽略不会报错。 权限与隐私目录 API 的安全设计目录 API 在隐私保护上考虑得很周到可见性判断逻辑isIndexVisibleweb/handler/index/index.go规定公开目录所有人可见私有目录仅创建者本人可见已删除目录一律不可见另外如果目录中包含 NSFW成人内容且用户未开启相关偏好查询结果也会被自动过滤。这些细节都体现在领域层接口 internal/index/domain.go 中读一遍代码就能对整体设计一目了然。❓ 常见问题FAQQ没有登录 Token 能调用目录 API 吗A查询公开目录可以但创建、修改、收藏等写操作必须登录并携带 Token。Q一个目录最多能放多少条目A目录本身没有硬性数量限制但列表接口默认分页返回建议配合分页参数逐页获取。Q想深入学习实现细节从哪里看起A推荐按这个顺序阅读源码路由 web/routes.go → Handler web/handler/index/ → 领域接口 internal/index/domain.go由外向内层层深入很快就能掌握这个项目的分层设计。现在去创建你的第一个专属条目合集吧无论是私人补番清单还是想分享给社区的年度盘点Bangumi Server 的目录 API都能帮你轻松实现 【免费下载链接】serverAPI server for bgm.tv项目地址: https://gitcode.com/gh_mirrors/server17/server创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考