开发者必看：YaSQL API接口文档与二次开发实战案例-平芜编程栈

开发者必看：YaSQL API接口文档与二次开发实战案例

【免费下载链接】YaSQL数据库工单平台，支持MySQL和TiDB，提供工单、审批流、数据查询功能项目地址: https://gitcode.com/gh_mirrors/ya/YaSQL

YaSQL作为一款功能强大的数据库工单平台，专为MySQL和TiDB数据库设计，提供了全面的工单管理、审批流程和数据查询功能。本文将详细介绍YaSQL的API接口文档结构，并通过实战案例展示如何进行二次开发，帮助开发者快速上手并扩展平台功能。

一、API接口概览：轻松掌握核心功能

YaSQL的API接口采用RESTful设计风格，主要分布在backend/internal/orders/routers/api.go文件中，涵盖了工单管理、任务执行、审批流程等核心功能模块。通过这些接口，开发者可以轻松实现与平台的交互，构建自定义的业务逻辑和前端界面。

1.1 工单管理接口

工单管理是YaSQL的核心功能之一，提供了从创建到完成的全生命周期管理。主要接口包括：

创建工单：POST /api/v1/orders
获取工单列表：GET /api/v1/orders
获取工单详情：GET /api/v1/orders/:order_id
工单操作：包括审批、认领、转移、撤销等，如PUT /api/v1/orders/actions/approval

1.2 任务执行接口

任务执行接口允许开发者提交和管理数据库操作任务，确保SQL脚本的安全执行。主要接口包括：

生成执行任务：POST /api/v1/orders/tasks
获取任务列表：GET /api/v1/orders/tasks/:order_id
执行任务：POST /api/v1/orders/tasks/execute
批量执行任务：POST /api/v1/orders/tasks/execute-batch

1.3 数据查询接口

数据查询接口提供了对数据库环境、实例和模式的查询能力，方便开发者获取必要的元数据信息。主要接口包括：

获取环境列表：GET /api/v1/orders/environments
获取实例列表：GET /api/v1/orders/instances
获取模式列表：GET /api/v1/orders/schemas

二、接口调用实战：从零开始集成YaSQL

2.1 环境准备

在开始集成YaSQL API之前，需要确保以下环境准备就绪：

获取源代码：通过Git克隆YaSQL仓库到本地
```
git clone https://gitcode.com/gh_mirrors/ya/YaSQL
```
配置后端服务：根据backend/config.yaml.template创建config.yaml，并配置数据库连接等信息
启动服务：进入backend目录，执行go run cmd/main.go启动后端API服务

2.2 创建工单示例

以下是使用curl命令创建工单的示例，展示了如何通过API接口与YaSQL进行交互：

curl -X POST http://localhost:8080/api/v1/orders \ -H "Content-Type: application/json" \ -H "Authorization: Bearer {your_token}" \ -d '{ "title": "添加用户表备注字段", "sql_content": "ALTER TABLE users ADD COLUMN remark VARCHAR(255) NOT NULL DEFAULT '';'", "environment_id": 1, "instance_id": 1, "schema_name": "test", "approver_ids": [1001, 1002] }'

成功调用后，API将返回新创建的工单ID和状态信息，开发者可以根据返回结果进行后续操作。

2.3 工单列表查询

通过以下API调用，可以获取当前用户有权限查看的工单列表：

curl -X GET "http://localhost:8080/api/v1/orders?status=PENDING&page=1&size=10" \ -H "Authorization: Bearer {your_token}"

返回结果将包含工单的基本信息，如工单ID、标题、提交人、状态等，方便开发者构建自定义的工单管理界面。

图：YaSQL工单列表界面，展示了系统中所有工单的状态和基本信息

三、二次开发案例：扩展审批流程功能

3.1 需求分析

在实际应用中，不同企业可能有不同的审批流程需求。本案例将展示如何扩展YaSQL的审批流程功能，添加自定义的审批节点和条件。

3.2 实现步骤

修改数据模型：在backend/internal/orders/models/models.go中添加自定义审批节点字段
扩展API接口：在backend/internal/orders/routers/api.go中添加新的审批流程管理接口
实现业务逻辑：在backend/internal/orders/services/approval_definition.go中实现自定义审批逻辑
前端界面调整：在www/src/views/admin/perms/flows/ApprovalFlowFormModal.vue中添加自定义审批节点配置界面

3.3 关键代码示例

以下是在approval_definition.go中添加自定义审批条件的示例代码：

// 自定义审批条件检查 func CheckCustomApprovalCondition(order *models.Order, approverID int64) bool { // 示例：当工单涉及核心表时，需要技术总监审批 if strings.Contains(order.SQLContent, "core_") { role, _ := userservice.GetUserRole(approverID) return role == "TECH_DIRECTOR" } return true }

通过这种方式，开发者可以根据企业实际需求，灵活定制审批流程，满足不同场景的业务需求。

图：YaSQL工单提交界面，用户可以输入SQL内容并选择审批流程

四、API安全与权限控制

YaSQL提供了完善的API安全和权限控制机制，确保只有授权用户才能访问和操作敏感接口。主要通过以下方式实现：

JWT认证：所有API请求需要携带有效的JWT令牌，在backend/middleware/jwt.go中实现
权限中间件：通过backend/middleware/permissions.go中的HasAdminPermission等中间件控制接口访问权限
数据隔离：基于组织和角色的数据访问控制，在backend/internal/users/services/org_scope.go中实现

开发者在进行二次开发时，应遵循这些安全机制，确保API调用的安全性和合规性。