bagisto-api-develop

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Developing the Bagisto API package

Bagisto API包开发指南

Use this when you are working inside the

bagisto-api

package (

packages/Webkul/BagistoApi

, namespace

Webkul\BagistoApi

) — installing it, removing it, adding or changing an endpoint/resource, or fixing package behaviour. This is the guide rails: it tells you where the authoritative spec is, the rules you must not break, and points you at the detailed references.

本指南适用于在

bagisto-api

包（路径

packages/Webkul/BagistoApi

，命名空间

Webkul\BagistoApi

）内进行的操作——安装包、卸载包、添加或修改端点/资源，或修复包的行为。本指南为你提供规范指引：告知你权威规范的位置、必须遵守的规则，并指向详细参考文档。

CRITICAL — install / remove only when asked

重要提醒——仅在明确要求时进行安装/卸载

Installing or removing the package is NEVER an automatic action. Detecting the package files, a

composer.json

, or a Bagisto project does not mean you should install, reinstall, optimise, or uninstall anything. Only perform install (

reference/install.md

) or removal (

reference/uninstall.md

) when the client explicitly asks for it, and for install, ask whether they want the Composer (stable) or Manual (newest) method first.

安装或卸载包绝不能自动执行。检测到包文件、
composer.json
或Bagisto项目，并不意味着你应该进行安装、重新安装、优化或卸载操作。只有当客户明确要求时，才可执行安装（参考

reference/install.md

）或卸载（参考

reference/uninstall.md

）操作；执行安装前，需先询问客户希望使用**Composer（稳定版）还是手动安装（最新版）**方式。

Authoritative sources — read these FIRST

权威资料——请先阅读这些内容

The package ships its own complete documentation. Read the relevant part before writing code — almost every menu/resource is already specified with its exact behaviour, validation, events, and quirks:

Source	What it gives you
`CLAUDE.md` (package root)	The authoritative conventions + a coverage table for every endpoint, with the per-resource decisions and quirks. Read this first for the resource you're touching.
`docs/superpowers/specs/`	Design specs for larger features.
`CHANGELOG.md`	What shipped, consumer-facing, under `[Unreleased]` .
`PERFORMANCE.md`	Caching / IRI / schema-build performance notes.
GitHub `bagisto/bagisto-api`	The canonical code — copy the closest existing resource rather than writing the pattern from scratch.
`https://api-docs.bagisto.com` (+ `/llms.txt` )	The consumer-facing request/response shapes + the full endpoint index.

Rule: don't improvise behaviour that
CLAUDE.md
already specifies. Search it for the resource/menu first.

该包自带完整文档。编写代码前请先阅读相关部分——几乎每个菜单/资源都已明确规定了其具体行为、验证规则、事件和特殊细节：

资料来源	提供内容
`CLAUDE.md` （包根目录）	权威约定 + 所有端点的覆盖表，包含每个资源的决策和特殊细节。处理对应资源前请先阅读此文档。
`docs/superpowers/specs/`	大型功能的设计规范。
`CHANGELOG.md`	已发布的面向用户的更新内容，查看 `[Unreleased]` 章节了解未发布内容。
`PERFORMANCE.md`	缓存/IRI/架构构建的性能说明。
GitHub `bagisto/bagisto-api`	标准代码库——复制最接近的现有资源，而非从头编写模式。
`https://api-docs.bagisto.com` （+ `/llms.txt` ）	面向用户的请求/响应格式 + 完整端点索引。

**规则：不要自行设计

CLAUDE.md

已指定的行为。**请先在该文档中搜索对应资源/菜单。

Reference map — open the one you need

参考文档映射——按需打开对应文档

Topic	Reference file	Use when
Install the package	`reference/install.md`	Client asks to install / set up the API
Remove the package	`reference/uninstall.md`	Client asks to remove / uninstall the package
Where files go	`reference/structure.md`	Adding any file; finding the right directory + base class
Surfaces, transports, declaring a resource	`reference/api-structure.md`	Designing a new endpoint; understanding the 5-file pattern + feature surface
Coding standards + checklist	`reference/conventions.md`	Writing/reviewing a resource against the rules
Foot-guns	`reference/precautions.md`	Before you ship — the things that silently break
What the API will / won't do	`reference/limitations.md`	Scoping a feature; deciding "do we support this?"
Tests + cache cycle	`reference/testing.md`	Running/adding tests; the cache commands

主题	参考文件	使用场景
安装包	`reference/install.md`	客户要求安装/配置API时
卸载包	`reference/uninstall.md`	客户要求移除/卸载API时
文件存放位置	`reference/structure.md`	添加任何文件；查找正确目录和基类时
接口层、传输层、声明资源	`reference/api-structure.md`	设计新端点；了解5文件模式和功能范围时
编码标准 + 检查清单	`reference/conventions.md`	编写/审核资源以符合规则时
常见陷阱	`reference/precautions.md`	发布前检查——那些会静默导致故障的问题
API支持/不支持的功能	`reference/limitations.md`	确定功能范围；判断“是否支持该功能”时
测试 + 缓存周期	`reference/testing.md`	运行/添加测试；执行缓存命令时

The 5-file pattern (the spine of every resource)

5文件模式（每个资源的核心架构）

Model (

#[ApiResource]

— REST + GraphQL ops + OpenAPI block) → DTO (typed input) → Provider (read path) → Processor (write path) → lang (

src/Resources/lang/en/app.php

). Storefront resources live under

src/

; admin resources under

src/Admin/

. Tag every Provider/Processor in
BagistoApiServiceProvider::register()
— an untagged one is silently bypassed (404 / wrong data). Full detail in

reference/api-structure.md

and

reference/structure.md

Model（

#[ApiResource]

——REST + GraphQL操作 + OpenAPI块）→ DTO（类型化输入）→ Provider（读取路径）→ Processor（写入路径）→ lang（

src/Resources/lang/en/app.php

）。前台资源存放在

src/

下；后台资源存放在

src/Admin/

下。必须在
BagistoApiServiceProvider::register()
中标记每个Provider/Processor——未标记的Provider/Processor会被静默忽略（导致404/数据错误）。详细内容请查看

reference/api-structure.md

和

reference/structure.md

。

The two non-negotiables

两项不可协商的规则

A REST change can break GraphQL — they share the same Provider/Processor. Always run the resource's GraphQL test before the REST test, and confirm it's green before considering the change done. This is the single most important rule.
Parity with the Bagisto admin panel, not a superset. Mirror what the admin UI does; where core lacks a feature, block the gap with a clear error rather than half-extending. See
```
reference/limitations.md
```
.

Everything else — the full checklist, the ranked foot-guns, and the test/cache commands — is in the references above. Open them rather than guessing.

REST接口的修改可能会破坏GraphQL——两者共享相同的Provider/Processor。请先运行资源的GraphQL测试，再运行REST测试，并确认GraphQL测试通过后，才可认为修改完成。这是最重要的一条规则。
**与Bagisto后台面板保持一致，不做超集扩展。**镜像后台UI的功能；若核心系统缺少某功能，需返回清晰的错误提示，而非半吊子扩展。详情请查看
```
reference/limitations.md
```
。

其他所有内容——完整检查清单、重点陷阱、测试/缓存命令——都在上述参考文档中。请打开对应文档查看，不要自行猜测。