跳到主要内容

工具开发最佳实践

本文档总结了在 GeniSpace 平台上开发和维护工具的最佳实践，帮助您创建高质量、可维护的工具。

设计原则​

1. 单一职责原则​

每个工具应该专注于一个明确的功能领域，避免功能过于复杂。

✅ 好的设计：

{
  "name": "用户认证工具",
  "description": "专门处理用户登录、注册、密码重置等认证相关功能",
  "methods": [
    "login",
    "register", 
    "resetPassword",
    "validateToken"
  ]
}

❌ 避免的设计：

{
  "name": "用户管理工具",
  "description": "处理用户、订单、支付、通知等所有功能",
  "methods": [
    "login", "createOrder", "sendEmail", "processPayment"
  ]
}

2. 接口稳定性​

设计稳定的输入输出接口，避免频繁的破坏性变更。

版本兼容策略：

  • 新增字段时提供默认值
  • 废弃字段时保持向后兼容
  • 重大变更时升级主版本号
{
  "inputSchema": {
    "type": "object",
    "properties": {
      "userId": {
        "type": "string",
        "title": "用户ID"
      },
      "includeProfile": {
        "type": "boolean",
        "title": "包含详细信息",
        "default": false  // 新增字段提供默认值
      },
      "format": {
        "type": "string",
        "title": "返回格式",
        "enum": ["json", "xml"],
        "default": "json",
        "deprecated": false  // 标记废弃状态
      }
    }
  }
}

3. 错误处理机制​

实现完善的错误处理和用户友好的错误信息。

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "success": {
        "type": "boolean",
        "title": "执行状态"
      },
      "data": {
        "type": "object",
        "title": "返回数据"
      },
      "error": {
        "type": "object",
        "title": "错误信息",
        "properties": {
          "code": {
            "type": "string",
            "title": "错误代码"
          },
          "message": {
            "type": "string", 
            "title": "错误描述"
          },
          "details": {
            "type": "object",
            "title": "详细信息"
          }
        }
      }
    }
  }
}

Schema 设计最佳实践​

1. 清晰的命名规范​

使用有意义、一致的命名规范：

{
  "properties": {
    // ✅ 清晰的命名
    "userId": {"type": "string", "title": "用户ID"},
    "userName": {"type": "string", "title": "用户名"},
    "userEmail": {"type": "string", "title": "用户邮箱"},
    
    // ❌ 避免的命名
    "id": {"type": "string"},  // 不够具体
    "data": {"type": "object"},  // 过于通用
    "temp": {"type": "string"}  // 临时性命名
  }
}

2. 详细的字段描述​

为每个字段提供清晰的描述和使用说明：

{
  "properties": {
    "timeout": {
      "type": "number",
      "title": "超时时间",
      "description": "API 请求的超时时间，单位为毫秒。建议设置为 30000-60000 之间",
      "minimum": 1000,
      "maximum": 300000,
      "default": 30000
    },
    "retryPolicy": {
      "type": "object",
      "title": "重试策略",
      "description": "当请求失败时的重试配置。设置为 null 表示不重试",
      "properties": {
        "maxAttempts": {
          "type": "number",
          "title": "最大重试次数",
          "description": "失败后的最大重试次数，0 表示不重试",
          "minimum": 0,
          "maximum": 10,
          "default": 3
        }
      }
    }
  }
}

3. 合理的验证规则​

添加适当的验证规则，但避免过度限制：

{
  "properties": {
    "email": {
      "type": "string",
      "title": "邮箱地址",
      "format": "email",
      "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
    },
    "phoneNumber": {
      "type": "string", 
      "title": "手机号码",
      "pattern": "^1[3-9]\\d{9}$",
      "description": "中国大陆手机号码格式"
    },
    "age": {
      "type": "integer",
      "title": "年龄",
      "minimum": 0,
      "maximum": 150
    }
  }
}

4. 端口标识的使用​

正确使用 isPort 标识区分端口参数和配置参数：

{
  "inputSchema": {
    "type": "object",
    "properties": {
      // 工作流连接端口
      "inputData": {
        "type": "object",
        "title": "输入数据",
        "isPort": true,
        "description": "来自上游节点的数据"
      },
      "filterCondition": {
        "type": "string",
        "title": "过滤条件", 
        "isPort": true,
        "description": "数据过滤条件"
      },
      
      // 配置参数
      "outputFormat": {
        "type": "string",
        "title": "输出格式",
        "isPort": false,
        "enum": ["json", "csv", "xml"],
        "default": "json"
      }
    }
  }
}

配置管理最佳实践​

1. 分层配置设计​

合理区分工具级配置和方法级配置：

{
  // 工具级配置 - 全局通用
  "configuration": {
    "schema": {
      "properties": {
        "serverUrl": {
          "type": "string",
          "title": "服务器地址",
          "description": "API 服务器的基础地址"
        },
        "globalTimeout": {
          "type": "number", 
          "title": "全局超时时间",
          "default": 30000
        }
      }
    }
  },
  
  // 方法级配置 - 特定于方法
  "methods": [{
    "configuration": {
      "schema": {
        "properties": {
          "endpoint": {
            "type": "string",
            "title": "接口路径",
            "description": "相对于服务器地址的具体接口路径"
          },
          "method": {
            "type": "string",
            "title": "HTTP 方法",
            "enum": ["GET", "POST", "PUT", "DELETE"]
          }
        }
      }
    }
  }]
}

2. 敏感信息处理​

正确处理敏感配置信息：

{
  "systemConfiguration": {
    "schema": {
      "properties": {
        "apiKey": {
          "type": "string",
          "title": "API 密钥",
          "format": "password",  // 标记为敏感信息
          "description": "用于 API 认证的密钥"
        },
        "databaseUrl": {
          "type": "string",
          "title": "数据库连接",
          "format": "password",
          "description": "数据库连接字符串"
        }
      }
    }
  }
}

3. 环境相关配置​

支持不同环境的配置：

{
  "configuration": {
    "schema": {
      "properties": {
        "environment": {
          "type": "string",
          "title": "运行环境",
          "enum": ["development", "staging", "production"],
          "default": "production"
        },
        "debugMode": {
          "type": "boolean",
          "title": "调试模式",
          "default": false,
          "description": "开启后会输出详细的调试信息"
        }
      }
    }
  }
}

性能优化​

1. 缓存策略​

为适合的操作实现缓存机制：

{
  "configuration": {
    "schema": {
      "properties": {
        "caching": {
          "type": "object",
          "title": "缓存配置",
          "properties": {
            "enabled": {
              "type": "boolean",
              "title": "启用缓存",
              "default": false
            },
            "ttlSeconds": {
              "type": "number",
              "title": "缓存时间",
              "description": "缓存有效期（秒）",
              "default": 3600,
              "minimum": 60,
              "maximum": 86400
            },
            "maxSize": {
              "type": "number",
              "title": "缓存大小",
              "description": "最大缓存条目数",
              "default": 1000,
              "minimum": 10
            }
          }
        }
      }
    }
  }
}

2. 超时和重试​

设置合理的超时和重试策略：

{
  "configuration": {
    "schema": {
      "properties": {
        "timeout": {
          "type": "number",
          "title": "请求超时",
          "description": "单次请求的超时时间（毫秒）",
          "default": 30000,
          "minimum": 1000,
          "maximum": 300000
        },
        "retryPolicy": {
          "type": "object",
          "title": "重试策略",
          "properties": {
            "maxAttempts": {
              "type": "number",
              "title": "最大重试次数",
              "default": 3,
              "minimum": 0,
              "maximum": 10
            },
            "backoffMultiplier": {
              "type": "number",
              "title": "退避倍数",
              "description": "每次重试的延迟倍数",
              "default": 2.0,
              "minimum": 1.0
            },
            "initialDelayMs": {
              "type": "number",
              "title": "初始延迟",
              "description": "首次重试前的延迟时间（毫秒）",
              "default": 1000,
              "minimum": 100
            }
          }
        }
      }
    }
  }
}

3. 资源限制​

为容器类型工具设置合理的资源限制：

{
  "systemConfiguration": {
    "schema": {
      "properties": {
        "resources": {
          "type": "object",
          "title": "资源限制",
          "properties": {
            "memory": {
              "type": "string",
              "title": "内存限制",
              "default": "512Mi",
              "pattern": "^\\d+[KMGT]i?$"
            },
            "cpu": {
              "type": "string", 
              "title": "CPU 限制",
              "default": "0.5",
              "pattern": "^\\d+(\\.\\d+)?$"
            },
            "timeout": {
              "type": "number",
              "title": "执行超时",
              "description": "容器执行的最大时间（秒）",
              "default": 300,
              "minimum": 10,
              "maximum": 3600
            }
          }
        }
      }
    }
  }
}

安全最佳实践​

1. 输入验证​

严格验证所有输入数据：

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "sqlQuery": {
        "type": "string",
        "title": "SQL 查询",
        "pattern": "^SELECT\\s+.*",  // 只允许 SELECT 语句
        "maxLength": 1000,
        "description": "只支持 SELECT 查询语句"
      },
      "filePath": {
        "type": "string",
        "title": "文件路径",
        "pattern": "^[a-zA-Z0-9/._-]+$",  // 限制文件路径字符
        "description": "文件路径不能包含特殊字符"
      }
    }
  }
}

2. 权限控制​

实现适当的访问控制：

{
  "systemConfiguration": {
    "schema": {
      "properties": {
        "accessControl": {
          "type": "object",
          "title": "访问控制",
          "properties": {
            "allowedRoles": {
              "type": "array",
              "title": "允许的角色",
              "items": {"type": "string"},
              "default": ["user"]
            },
            "requireAuthentication": {
              "type": "boolean",
              "title": "需要认证",
              "default": true
            }
          }
        }
      }
    }
  }
}

3. 审计日志​

记录重要操作的审计日志：

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "result": {
        "type": "object",
        "title": "执行结果"
      },
      "auditLog": {
        "type": "object",
        "title": "审计日志",
        "properties": {
          "operationId": {"type": "string", "title": "操作ID"},
          "userId": {"type": "string", "title": "用户ID"},
          "timestamp": {"type": "string", "title": "操作时间"},
          "action": {"type": "string", "title": "操作类型"},
          "resource": {"type": "string", "title": "操作资源"}
        }
      }
    }
  }
}

测试和质量保证​

1. 单元测试​

为工具编写完整的测试用例：

{
  "testCases": [
    {
      "name": "正常用户查询",
      "input": {
        "userId": "12345",
        "includeProfile": true
      },
      "expectedOutput": {
        "success": true,
        "data": {
          "id": "12345",
          "name": "张三"
        }
      }
    },
    {
      "name": "用户不存在",
      "input": {
        "userId": "99999"
      },
      "expectedOutput": {
        "success": false,
        "error": {
          "code": "USER_NOT_FOUND",
          "message": "用户不存在"
        }
      }
    }
  ]
}

2. 集成测试​

在实际工作流中测试工具：

{
  "integrationTests": [
    {
      "workflow": "用户数据处理流程",
      "steps": [
        "数据输入 → 用户查询工具 → 数据转换工具 → 结果输出"
      ],
      "testData": {
        "userIds": ["1", "2", "3"]
      },
      "expectedResults": {
        "processedUsers": 3,
        "errors": 0
      }
    }
  ]
}

3. 性能测试​

验证工具在高负载下的表现：

{
  "performanceTests": [
    {
      "name": "并发用户查询",
      "concurrency": 100,
      "duration": "60s",
      "expectedMetrics": {
        "averageResponseTime": "< 500ms",
        "errorRate": "< 1%",
        "throughput": "> 200 req/s"
      }
    }
  ]
}

文档和维护​

1. 完整的文档​

为工具编写详细的使用文档：

# 用户管理工具

## 概述
用户管理工具提供用户信息的查询、创建、更新和删除功能。

## 方法列表

### getUserInfo - 获取用户信息
根据用户ID获取用户的详细信息。

**输入参数：**
- `userId` (string, 必填): 用户的唯一标识符
- `includeProfile` (boolean, 可选): 是否包含用户详细资料，默认为 false

**输出结果：**
- `user` (object): 用户信息对象
- `metadata` (object): 查询元数据

**使用示例：**
```json
{
  "userId": "12345",
  "includeProfile": true
}

错误处理：

  • USER_NOT_FOUND: 用户不存在
  • INVALID_USER_ID: 用户ID格式错误
  • ACCESS_DENIED: 没有访问权限

### 2. 版本更新日志

维护详细的版本更新记录：

```markdown
# 更新日志

## v1.2.0 (2024-01-15)
### 新增
- 添加批量用户查询方法
- 支持用户头像上传功能

### 改进
- 优化用户查询性能，响应时间减少 30%
- 增强错误信息的详细程度

### 修复
- 修复用户邮箱验证的正则表达式问题
- 解决并发查询时的数据竞争问题

## v1.1.0 (2024-01-01)
### 新增
- 添加用户权限验证
- 支持用户数据缓存

### 变更
- 调整用户ID格式验证规则（向后兼容）

3. 监控和告警​

设置关键指标的监控：

{
  "monitoring": {
    "metrics": [
      {
        "name": "response_time",
        "description": "工具响应时间",
        "threshold": "500ms",
        "alertLevel": "warning"
      },
      {
        "name": "error_rate", 
        "description": "错误率",
        "threshold": "5%",
        "alertLevel": "critical"
      },
      {
        "name": "throughput",
        "description": "处理吞吐量",
        "threshold": "100 req/min",
        "alertLevel": "info"
      }
    ]
  }
}

常见问题和解决方案​

1. 性能问题​

问题： 工具响应时间过长 解决方案：

  • 启用缓存机制
  • 优化数据库查询
  • 增加超时和重试配置
  • 考虑异步处理

2. 兼容性问题​

问题： 新版本工具与旧工作流不兼容 解决方案：

  • 保持向后兼容的接口设计
  • 使用版本号管理
  • 提供迁移指南
  • 支持多版本并存

3. 安全问题​

问题： 敏感信息泄露 解决方案：

  • 使用系统配置存储敏感信息
  • 实现适当的访问控制
  • 添加审计日志
  • 定期安全审查

相关文档​