📋 目录
前端基础（React）
- Component（组件） - React的基础概念，就像搭积木的积木块
- State（状态） - 组件如何管理数据，比如"按钮是否被点击"
- Hook（钩子） - React的函数式编程方式，如useState、useEffect
- Props（属性） - 组件之间传递数据的方式
后端基础（Go）
- Struct（结构体） - Go语言的数据结构，类似其他语言的类
- Interface（接口） - Go语言的接口概念，定义"能做什么"
- Package（包） - Go语言的代码组织单位
- [Error Handling（错误处理）](#Error Handling（错误处理）) - Go语言的错误处理方式
Workflow核心概念
- Canvas（画布） - Workflow的可视化编辑界面
- Node（节点） - Workflow的执行单元，每个节点执行一个操作
- Edge（边） - 连接节点的线，表示数据流向
- Schema（模式） - Workflow的执行时格式
通信基础
- API - 前后端通信的方式
- Request/Response（请求/响应） - API调用的基本概念
💡 提示：理解这些术语后，建议按照以下顺序阅读文档：
前端术语
React相关
Component（组件）
简单理解：组件就像搭积木，每个积木块就是一个组件。比如一个按钮是一个组件，一个表单也是一个组件。你可以把多个组件组合起来，形成一个完整的页面。
定义：React组件是构建用户界面的基本单元，可以复用。
详细解释：组件是React的核心概念，类似于函数，接收输入（props）并返回描述UI的React元素。组件可以是函数组件或类组件。函数组件是使用函数定义的组件，更简洁；类组件是使用ES6类定义的组件，功能更强大。
代码示例：
typescript
// 函数组件示例（推荐方式）
function MyComponent(props: { name: string }) {
return <div>Hello, {props.name}!</div>;
}
// 箭头函数形式
const MyComponent = (props: { name: string }) => {
return <div>Hello, {props.name}!</div>;
}
// 在项目中的实际使用
// 文件：frontend/packages/workflow/components/src/workflow-edit/index.tsx
export function CreateWorkflowModal({
flowMode = WorkflowMode.Workflow,
mode,
// ... 其他props
}: CreateWorkflowModalProps) {
// 组件实现
}使用场景：用于构建UI界面，每个页面、按钮、表单等都是组件。组件可以嵌套使用，形成组件树。
Hook（钩子）
定义：Hook是React 16.8引入的特殊函数，让函数组件可以使用状态和其他React特性。
详细解释：Hook以"use"开头，如useState、useEffect。Hook只能在函数组件或自定义Hook中调用，不能在普通函数中调用。Hook让函数组件拥有类组件的能力。
常用Hooks：
- useState：管理组件状态
typescript
// 文件：frontend/packages/workflow/test-run/src/components/testset/select/use-testset-options.ts
const [loading, setLoading] = useState(false);
// useState返回一个数组：[当前值, 更新函数]
// loading是当前状态值，setLoading是更新状态的函数- useEffect：处理副作用（数据获取、订阅、DOM操作等）
typescript
useEffect(() => {
// 组件挂载或更新时执行
loadData();
// 返回清理函数（可选）
return () => {
// 组件卸载时执行清理
};
}, [dependencies]); // 依赖数组，只有依赖变化时才执行- useCallback：缓存函数，避免不必要的重新创建
typescript
// 文件：frontend/packages/workflow/test-run/src/components/testset/select/use-testset-options.ts
const setOptionsDataWithCache = useCallback(
(val: OptionsData) => {
setOptionsData(val);
optionsDataRef.current = val;
},
[setOptionsData, optionsDataRef, optionsCacheRef], // 依赖数组
);- useRef：获取DOM引用或保存可变值
typescript
const optionsDataRef = useRef(optionsData);
// useRef返回的对象在组件整个生命周期中保持不变
// 修改ref.current不会触发重新渲染使用场景：在函数组件中管理状态、处理副作用、优化性能。
Props（属性）
定义：Props是组件接收的参数，用于从父组件向子组件传递数据。
详细解释：Props是只读的（immutable），子组件不能修改props。Props可以是任何类型：字符串、数字、对象、函数等。通过props，组件可以接收外部数据和行为。
代码示例：
typescript
// 定义Props类型
interface CreateWorkflowModalProps {
flowMode?: WorkflowMode;
mode: string;
visible: boolean;
onClose: () => void;
}
// 使用Props
function CreateWorkflowModal(props: CreateWorkflowModalProps) {
// 访问props
const { flowMode, mode, visible, onClose } = props;
return (
<Modal visible={visible} onClose={onClose}>
{/* 使用props */}
</Modal>
);
}
// 传递Props
<CreateWorkflowModal
flowMode={WorkflowMode.Workflow}
mode="create"
visible={true}
onClose={() => {}}
/>使用场景：父组件向子组件传递数据、回调函数、配置等。
State（状态）
定义：State是组件内部的数据，可以变化并触发重新渲染。
详细解释：State是组件的私有数据，只有组件本身可以修改。当state改变时，React会重新渲染组件。使用useState Hook来管理state。
代码示例：
typescript
// 文件：frontend/packages/workflow/test-run/src/components/testset/select/use-testset-options.ts
// 1. 声明state
const [loading, setLoading] = useState(false);
// loading是当前状态值，初始值为false
// setLoading是更新函数
// 2. 更新state
setLoading(true); // 设置loading为true
// 3. 使用state
if (loading) {
return <div>加载中...</div>;
}
// 4. 对象state
const [optionsData, setOptionsData] = useState<OptionsData>({ list: [] });
// 更新对象state（需要创建新对象）
setOptionsData({
...optionsData, // 展开旧对象
list: newList // 更新list字段
});State vs Props：
- Props：从父组件传入，只读
- State：组件内部管理，可读写
使用场景：存储用户输入、UI状态（展开/收起）、加载状态等。
Context（上下文）
定义：Context提供了一种在组件树中共享数据的方式，避免逐层传递props。
详细解释：当需要在多个组件间共享数据时，使用Context比逐层传递props更方便。Context包含Provider（提供数据）和Consumer（消费数据）。
代码示例：
typescript
// 文件：frontend/packages/workflow/test-run/src/components/testset/use-testset-manage-store.ts
// 1. 使用Context
const store = useContext(TestsetManageContext);
// useContext从最近的Provider获取值
// 2. 在Provider中使用
<TestsetManageContext.Provider value={store}>
{/* 子组件可以访问store */}
<ChildComponent />
</TestsetManageContext.Provider>使用场景：主题、用户信息、全局状态等在多个组件间共享的数据。
Render（渲染）
定义：Render是React将组件转换为DOM元素的过程。
详细解释：当组件的state或props改变时，React会重新执行render函数，生成新的虚拟DOM，然后与旧的虚拟DOM比较（diff），最后更新实际DOM。
代码示例：
typescript
function MyComponent({ name }: { name: string }) {
// 这是render函数
return (
<div>
<h1>Hello, {name}!</h1>
{/* React会将JSX转换为DOM元素 */}
</div>
);
}渲染流程：
- 组件state/props改变
- React调用render函数
- 生成虚拟DOM
- 与旧虚拟DOM比较（diff算法）
- 更新实际DOM（只更新变化的部分）
使用场景：理解React如何更新UI，优化性能。
状态管理
Zustand
定义：Zustand是一个轻量级的React状态管理库。
详细解释：Zustand提供了简单直观的API来管理全局状态，不需要Provider包裹，使用起来比Redux更简单。适合中小型应用的状态管理。
代码示例：
typescript
// 文件：frontend/packages/workflow/base/src/store/workflow.ts
import { create } from 'zustand';
// 定义store
interface WorkflowStore {
nodes: Node[];
edges: Edge[];
setNodes: (nodes: Node[]) => void;
setEdges: (edges: Edge[]) => void;
}
// 创建store
const useWorkflowStore = create<WorkflowStore>((set) => ({
nodes: [],
edges: [],
setNodes: (nodes) => set({ nodes }),
setEdges: (edges) => set({ edges }),
}));
// 在组件中使用
function MyComponent() {
const nodes = useWorkflowStore((state) => state.nodes);
const setNodes = useWorkflowStore((state) => state.setNodes);
// 更新状态
setNodes([...nodes, newNode]);
}使用场景：管理全局状态，如用户信息、主题、Workflow数据等。
Store（存储）
定义：Store是状态管理库中存储状态的地方。
详细解释：Store包含应用的状态数据和更新状态的方法。Zustand的store是一个Hook，可以直接在组件中使用。
代码示例：
typescript
// 使用Zustand store
const { nodes, setNodes } = useWorkflowStore();
// 使用Selector选择部分状态（性能优化）
const nodes = useWorkflowStore((state) => state.nodes);
// 只有nodes变化时组件才会重新渲染使用场景：存储需要跨组件共享的状态。
Selector（选择器）
定义：Selector是用于从store中选择特定数据的函数。
详细解释：使用Selector可以只订阅store的一部分数据，避免不必要的重新渲染，提高性能。
代码示例：
typescript
// 文件：frontend/packages/workflow/test-run/src/components/testset/use-testset-manage-store.ts
export const useTestsetManageStore = <T>(
selector: (s: TestsetManageState & TestsetManageAction) => T,
) => {
const store = useContext(TestsetManageContext);
// selector函数选择需要的状态
return useStore(store, selector, shallow);
};
// 使用Selector
const { bizComponentSubject } = useTestsetManageStore(store => store);
// 只选择bizComponentSubject，其他状态变化不会触发重新渲染使用场景：优化性能，只订阅需要的数据。
架构相关
Monorepo
简单理解：通常一个项目一个仓库，但Monorepo是把多个相关项目放在一个仓库里。就像把多个房间放在一栋楼里，方便管理和共享资源。
定义：Monorepo是将多个相关项目放在同一个代码仓库中的代码组织方式。
详细解释：Coze Studio前端使用Monorepo架构，所有packages都在一个仓库中，便于代码共享、版本管理和依赖管理。使用Rush和PNPM管理。
为什么每个包都有自己的src目录？
这是Monorepo与Java单仓库结构的主要区别：
Java项目（单仓库）：
java-project/
└── src/ # 只有一个src目录
├── main/java/
└── test/Monorepo（多包）：
frontend/
├── packages/
│ ├── workflow/base/
│ │ └── src/ # 每个包都有自己的src
│ ├── workflow/playground/
│ │ └── src/ # 每个包都有自己的src
│ └── arch/bot-api/
│ └── src/ # 每个包都有自己的src原因：
- 每个包是独立的模块 ：有自己的
package.json，可以独立发布 - 通过包名引用 ：
import { ... } from '@coze-workflow/base'，而不是相对路径 - 可以独立构建：每个包可以单独构建和测试
代码示例：
frontend/
├── packages/ # 所有包都在这里
│ ├── workflow/ # Workflow相关包
│ │ ├── base/
│ │ │ └── src/ # base包的源代码
│ │ └── playground/
│ │ └── src/ # playground包的源代码
│ ├── arch/ # 架构层包
│ │ └── bot-api/
│ │ └── src/ # bot-api包的源代码
│ └── common/ # 通用包
│ └── src/ # common包的源代码
├── apps/ # 应用
│ └── coze-studio/ # 主应用
│ └── src/ # 应用的源代码
└── rush.json # Rush配置文件使用场景：大型项目，需要多个相关包协同开发。
相关术语 ：Package
Dependency Injection（依赖注入）
定义：依赖注入是一种设计模式，将依赖从外部传入，而不是在内部创建。
详细解释：在前端使用InversifyJS实现依赖注入，让代码更解耦、更易测试。
代码示例：
typescript
// 文件：frontend/packages/workflow/playground/src/services/workflow-save-service.ts
import { inject, injectable } from 'inversify';
// 1. 标记类为可注入
@injectable()
export class WorkflowSaveService {
// 2. 注入依赖
@inject(WorkflowGlobalStateEntity)
globalState: WorkflowGlobalStateEntity;
@inject(WorkflowOperationService)
operationService: WorkflowOperationService;
// 使用依赖
save = async () => {
const projectApi = this.globalState.getProjectApi();
await this.operationService.save(json);
};
}使用场景：解耦组件依赖，便于测试和替换实现。
相关术语 ：[Adapter Pattern](#Adapter Pattern)
Adapter Pattern（适配器模式）
定义：适配器模式让不兼容的接口能够协同工作。
详细解释：在Coze Studio中，使用adapter包来适配不同的实现，如不同的编辑器、不同的存储等。
代码示例：
typescript
// adapter包通常以-adapter结尾
// frontend/packages/workflow/adapter/playground/
// 适配Playground编辑器到Workflow系统使用场景：集成第三方库、适配不同实现。
相关术语 ：[Dependency Injection](#Dependency Injection)
后端术语
Go语言相关
Package（包）
定义：Go语言的代码组织单位，每个目录下的.go文件属于同一个包。
详细解释：包是Go语言代码组织和复用的基本单位。同一个包内的代码可以互相访问，不同包之间通过导入（import）来使用。包名通常与目录名相同。
代码示例：
go
// 文件：backend/domain/workflow/service/service_impl.go
package service // 声明包名，必须与目录名相同
import (
"context" // 导入标准库
"github.com/coze-dev/coze-studio/backend/domain/workflow/entity" // 导入项目包
)
// 包内的函数、变量、类型等都可以被同包的其他文件访问使用场景：组织代码，实现模块化，控制可见性。
Import（导入）
定义：Import用于导入其他包，使用其公开的函数、类型等。
详细解释：Go使用import导入包，导入的包必须是已安装的。标准库直接导入，第三方包需要完整路径。
代码示例：
go
import (
"context" // 标准库，直接导入
"fmt" // 标准库
"github.com/coze-dev/coze-studio/backend/domain/workflow/entity" // 项目包
"gorm.io/gorm" // 第三方包
)使用场景：使用其他包的功能。
相关术语 ：Package
Struct（结构体）
定义：Struct是Go语言中定义自定义类型的方式，包含多个字段。
详细解释：Struct类似于其他语言中的类，但没有方法继承。Struct可以包含不同类型的字段，每个字段有名称和类型。
代码示例：
go
// 文件：backend/domain/workflow/entity/vo/canvas.go
type Canvas struct {
Nodes []*Node `json:"nodes"` // 字段名 类型 标签
Edges []*Edge `json:"edges"`
Versions any `json:"versions"`
}
// 使用struct
canvas := Canvas{
Nodes: []*Node{},
Edges: []*Edge{},
}
// 访问字段
nodes := canvas.Nodes使用场景：定义数据结构、实体、配置等。
Interface（接口）
定义：Interface定义了对象的行为，而不是实现。
详细解释：Go的接口是隐式实现的，只要类型实现了接口的所有方法，就实现了该接口。接口让代码更灵活，便于测试和替换实现。
代码示例：
go
// 文件：backend/domain/workflow/interface.go
type Repository interface {
CreateMeta(ctx context.Context, meta *vo.Meta) (int64, error)
GetMeta(ctx context.Context, id int64) (*vo.Meta, error)
// ... 其他方法
}
// 实现接口（隐式实现）
type RepositoryImpl struct {
DB *gorm.DB
}
func (r *RepositoryImpl) CreateMeta(ctx context.Context, meta *vo.Meta) (int64, error) {
// 实现
}
// 使用接口
func DoSomething(repo Repository) {
// 可以传入任何实现了Repository接口的类型
repo.CreateMeta(ctx, meta)
}使用场景：定义契约、依赖注入、多态。
Method（方法）
定义：Method是定义在类型上的函数，可以访问类型的字段。
详细解释：Go的方法有接收者（receiver），可以是值接收者或指针接收者。指针接收者可以修改原对象。
代码示例：
go
// 文件：backend/domain/workflow/entity/vo/canvas.go
type Node struct {
ID string
Type string
parent *Node
}
// 值接收者（不能修改原对象）
func (n Node) GetID() string {
return n.ID
}
// 指针接收者（可以修改原对象）
func (n *Node) SetParent(parent *Node) {
n.parent = parent
}
// 调用方法
node := &Node{ID: "123"}
node.SetParent(parentNode)
id := node.GetID()使用场景：为类型添加行为，实现面向对象编程。
Goroutine（协程）
定义：Goroutine是Go语言的轻量级线程，由Go运行时管理。
详细解释 ：Goroutine比线程更轻量，可以创建成千上万个。使用go关键字启动goroutine，多个goroutine可以并发执行。
代码示例：
go
// 文件：backend/domain/workflow/internal/compose/workflow_run.go
// 启动goroutine
go func() {
// 在后台执行
lastEventChan <- execute.HandleExecuteEvent(
ctx, executeID, eventChan, cancelFn, timeoutFn,
repo, sw, config)
}()
// 普通函数调用（同步）
doSomething()
// Goroutine调用（异步）
go doSomething()使用场景：并发处理、异步任务、事件处理。
Channel（通道）
定义：Channel是Go语言中用于goroutine之间通信的管道。
详细解释：Channel是类型安全的，只能传递指定类型的数据。可以是无缓冲的（同步）或有缓冲的（异步）。
代码示例：
go
// 文件：backend/domain/workflow/internal/compose/workflow_run.go
// 1. 创建channel
eventChan := make(chan *execute.Event) // 无缓冲channel
lastEventChan := make(chan *execute.Event, 1) // 有缓冲channel（容量1）
// 2. 发送数据
eventChan <- event
// 3. 接收数据
event := <-eventChan
// 4. 关闭channel
close(eventChan)
// 5. 遍历channel
for event := range eventChan {
// 处理事件
}
// 6. 只读channel（作为参数）
func HandleEvent(eventChan <-chan *execute.Event) {
// 只能接收，不能发送
event := <-eventChan
}使用场景：goroutine间通信、事件传递、同步。
Context（上下文）
定义：Context是Go语言中用于传递请求范围数据、取消信号和超时的标准接口。
详细解释：Context贯穿整个请求生命周期，用于传递用户ID、请求ID、取消信号等。Context是不可变的，创建新的Context而不是修改旧的。
代码示例：
go
// 文件：backend/domain/workflow/service/executable_impl.go
// 1. 创建根context
ctx := context.Background()
// 2. 创建可取消的context
ctx, cancel := context.WithCancel(ctx)
defer cancel() // 确保取消函数被调用
// 3. 创建带超时的context
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
// 4. 传递context
func DoSomething(ctx context.Context) error {
// 检查context是否已取消
if ctx.Err() != nil {
return ctx.Err()
}
// 执行操作
return nil
}
// 5. 从context获取值
logID, _ := ctx.Value(consts.CtxLogIDKey).(string)使用场景：传递请求数据、控制超时、取消操作。
Error Handling（错误处理）
定义：Go语言的错误处理模式，函数返回error表示是否出错。
详细解释：Go没有异常机制，使用返回值传递错误。error是接口类型，nil表示没有错误。调用者必须检查error。
代码示例：
go
// 文件：backend/domain/workflow/service/executable_impl.go
// 1. 返回错误
func DoSomething() error {
if somethingWrong {
return fmt.Errorf("error occurred: %w", originalErr)
// %w用于包装错误，保留原始错误
}
return nil // nil表示没有错误
}
// 2. 检查错误
err := DoSomething()
if err != nil {
// 处理错误
log.Printf("error: %v", err)
return err
}
// 3. 错误包装
func (i *impl) SyncExecute(...) (*entity.WorkflowExecution, error) {
wfEntity, err := i.Get(ctx, &vo.GetPolicy{...})
if err != nil {
return nil, err // 直接返回错误
}
// 包装错误
if err != nil {
return nil, fmt.Errorf("failed to create workflow: %w", err)
}
}使用场景：处理所有可能的错误情况。
相关术语 ：Interface
通用术语
Workflow相关
Workflow相关
Canvas（画布）
定义：Workflow的可视化编辑界面，包含节点和边的图形表示。
详细解释：Canvas是前端用于编辑Workflow的图形界面，用户可以在上面拖拽节点、连接节点。Canvas的数据结构包含nodes（节点数组）和edges（边数组）。前端Canvas和后端Canvas数据结构相同，通过JSON序列化传输。
代码示例：
go
// 后端Canvas数据结构
// 文件：backend/domain/workflow/entity/vo/canvas.go
type Canvas struct {
Nodes []*Node `json:"nodes"` // 节点列表
Edges []*Edge `json:"edges"` // 边列表
Versions any `json:"versions"` // 版本信息
}
// 前端Canvas数据结构（TypeScript）
// 类型定义类似
interface Canvas {
nodes: Node[];
edges: Edge[];
versions?: any;
}使用场景：保存和加载Workflow定义时使用，前端编辑器操作Canvas，后端存储Canvas。
Node（节点）
定义：Node是Workflow中的执行单元，代表一个操作或步骤。
详细解释：每个Node有类型（如LLM、代码、插件等）、配置数据、输入输出定义等。Node在Canvas上显示为图形元素，用户可以拖拽、配置。
代码示例：
go
// 文件：backend/domain/workflow/entity/vo/canvas.go
type Node struct {
ID string `json:"id"` // 节点唯一ID
Type string `json:"type"` // 节点类型：llm、code、plugin等
Meta any `json:"meta"` // 元数据：位置、样式等
Data *Data `json:"data"` // 节点配置数据
Blocks []*Node `json:"blocks,omitempty"` // 子节点（复合节点）
Edges []*Edge `json:"edges,omitempty"` // 连接的边
}
// 节点类型示例
const (
NodeTypeStart = "start" // 开始节点
NodeTypeEnd = "end" // 结束节点
NodeTypeLLM = "llm" // LLM节点
NodeTypeCode = "code" // 代码节点
NodeTypePlugin = "plugin" // 插件节点
NodeTypeSubWorkflow = "sub_workflow" // 子工作流节点
)使用场景：构建Workflow，每个节点执行特定功能。
Edge（边）
定义：Edge是连接两个Node的线，表示数据流向。
详细解释：Edge连接源节点和目标节点，定义数据如何从一个节点传递到另一个节点。Edge可以连接节点的特定端口（输入/输出）。
代码示例：
go
// 文件：backend/domain/workflow/entity/vo/canvas.go
type Edge struct {
SourceNodeID string `json:"sourceNodeID"` // 源节点ID
TargetNodeID string `json:"targetNodeID"` // 目标节点ID
SourcePortID string `json:"sourcePortID,omitempty"` // 源端口ID（可选）
TargetPortID string `json:"targetPortID,omitempty"` // 目标端口ID（可选）
}
// Edge示例
edge := Edge{
SourceNodeID: "node1",
TargetNodeID: "node2",
SourcePortID: "output",
TargetPortID: "input",
}
// 表示：node1的output端口连接到node2的input端口使用场景：定义Workflow的执行顺序和数据流向。
Schema（模式）
定义：Schema定义了Workflow的结构，包括节点类型、输入输出定义等。
详细解释：Schema是Workflow的执行时表示，由Canvas转换而来。Schema包含节点Schema、依赖关系、输入输出类型定义等。Schema用于验证和执行Workflow。
代码示例：
go
// 文件：backend/domain/workflow/internal/schema/workflow_schema.go
type WorkflowSchema struct {
nodes map[vo.NodeKey]*schema.NodeSchema // 节点Schema映射
edges []*Connection // 连接关系
inputs map[string]*vo.TypeInfo // 输入定义
outputs map[string]*vo.TypeInfo // 输出定义
}
// NodeSchema定义节点的输入输出
type NodeSchema struct {
Key string
Type string
Inputs map[string]*TypeInfo // 输入字段定义
Outputs map[string]*TypeInfo // 输出字段定义
InputSources map[string][]string // 输入来源（依赖关系）
}使用场景：Workflow执行时使用Schema，验证输入、解析依赖、执行节点。
Execution（执行）
定义：Execution是Workflow的一次运行实例。
详细解释：每次执行Workflow都会创建一个Execution记录，包含执行ID、状态、输入输出、执行时间等。Execution可以同步执行（等待完成）或异步执行（立即返回）。
代码示例：
go
// 文件：backend/domain/workflow/entity/workflow_execution.go
type WorkflowExecution struct {
ID int64 // 执行ID
WorkflowID int64 // Workflow ID
Status WorkflowExecuteStatus // 状态：Running、Success、Failed
Input *string // 输入（JSON字符串）
Output *string // 输出（JSON字符串）
Duration int64 // 执行时长（毫秒）
TokenInfo *TokenUsage // Token使用情况
}
// 执行状态
const (
WorkflowRunning WorkflowExecuteStatus = "running"
WorkflowSuccess WorkflowExecuteStatus = "success"
WorkflowFailed WorkflowExecuteStatus = "failed"
WorkflowInterrupted WorkflowExecuteStatus = "interrupted"
)使用场景：记录Workflow执行历史，查询执行结果，调试问题。
相关术语 ：Workflow、[Node Execution](#Node Execution)
API相关
RESTful API
定义：RESTful API是一种API设计风格，使用HTTP方法（GET、POST等）操作资源。
详细解释：REST（Representational State Transfer）使用URL表示资源，HTTP方法表示操作。GET获取资源，POST创建资源，PUT更新资源，DELETE删除资源。
代码示例：
go
// 文件：backend/api/handler/coze/workflow_service.go
// POST /api/workflow_api/create - 创建Workflow
func CreateWorkflow(ctx context.Context, c *app.RequestContext) {
var req workflow.CreateWorkflowRequest
c.BindAndValidate(&req)
// ...
}
// POST /api/workflow_api/save - 保存Workflow
func SaveWorkflow(ctx context.Context, c *app.RequestContext) {
var req workflow.SaveWorkflowRequest
c.BindAndValidate(&req)
// ...
}使用场景：前后端通信，提供标准化的API接口。
相关术语 ：Endpoint、Request/Response
Thrift IDL
定义：Thrift IDL（Interface Definition Language）是用于定义API接口的语言。
详细解释：IDL定义API的请求和响应结构，然后通过代码生成工具生成前后端的类型定义和客户端代码。这样保证前后端类型一致。
代码示例：
thrift
// 文件：idl/workflow/workflow_svc.thrift
namespace go workflow
service WorkflowService {
// 创建Workflow
workflow.CreateWorkflowResponse CreateWorkflow(
1: workflow.CreateWorkflowRequest request
) (api.post='/api/workflow_api/create', api.category="workflow_api")
// 保存Workflow
workflow.SaveWorkflowResponse SaveWorkflow(
1: workflow.SaveWorkflowRequest request
) (api.post='/api/workflow_api/save', api.category="workflow_api")
}
// 请求结构
struct CreateWorkflowRequest {
1: string name,
2: string space_id,
3: workflow.WorkflowMode flow_mode,
}
// 响应结构
struct CreateWorkflowResponse {
1: string workflow_id,
2: i64 create_time,
}使用场景：定义API接口，生成类型安全的客户端代码。
相关术语 ：[RESTful API](#RESTful API)、Request/Response
Request/Response（请求/响应）
定义：Request是客户端发送给服务器的数据，Response是服务器返回给客户端的数据。
详细解释：HTTP请求包含URL、方法、Headers、Body。响应包含状态码、Headers、Body。在Coze Studio中，请求和响应通常是JSON格式。
代码示例：
typescript
// 前端：发送请求
// 文件：frontend/packages/workflow/playground/src/services/workflow-operation-service.ts
await workflowApi.SaveWorkflow({
schema: JSON.stringify(json),
workflow_id: this.workflowId,
space_id: this.spaceId,
});
// 后端：处理请求
// 文件：backend/api/handler/coze/workflow_service.go
func SaveWorkflow(ctx context.Context, c *app.RequestContext) {
var req workflow.SaveWorkflowRequest
err = c.BindAndValidate(&req) // 绑定请求参数
resp, err := appworkflow.SVC.SaveWorkflow(ctx, &req)
c.JSON(consts.StatusOK, resp) // 返回JSON响应
}使用场景：前后端数据交换。
相关术语 ：[RESTful API](#RESTful API)、Endpoint
Endpoint（端点）
定义：Endpoint是API的URL路径，标识一个API接口。
详细解释 ：Endpoint由HTTP方法和URL路径组成，如POST /api/workflow_api/save。每个Endpoint对应一个处理函数。
代码示例：
go
// 文件：backend/api/router/coze/api.go
_workflow := _api.Group("/workflow_api", _workflowMw()...)
_workflow.POST("/save", append(_saveworkflowMw(), coze.SaveWorkflow)...)
// Endpoint: POST /api/workflow_api/save使用场景：标识和调用API接口。
相关术语 ：[RESTful API](#RESTful API)
术语索引
按类别索引
- React相关 ：Component、Hook、Props、State、Context、Render
- 状态管理 ：Zustand、Store、Selector
- 架构相关 ：Monorepo、[Dependency Injection](#Dependency Injection)、[Adapter Pattern](#Adapter Pattern)
- Go语言 ：Package、Import、Struct、Interface、Method、Goroutine、Channel、Context、[Error Handling](#Error Handling)
- 后端架构 ：DDD、[Repository Pattern](#Repository Pattern)、[Service Layer](#Service Layer)、[Domain Model](#Domain Model)
- Workflow ：Canvas、Node、Edge、Schema、Execution
- API ：[RESTful API](#RESTful API)、[Thrift IDL](#Thrift IDL)、Request/Response、Endpoint