Skip to main content

Operator Development Best Practices

This document summarizes best practices for developing and maintaining operators on the GeniSpace platform, helping you create high-quality, maintainable operators.

Design Principles​

1. Single Responsibility Principle​

Each operator should focus on a clearly defined functional area and avoid overly complex functionality.

✅ Good Design:

{
  "name": "User Authentication Tool",
  "description": "Handles user login, registration, password reset, and other authentication-related functions",
  "methods": [
    "login",
    "register", 
    "resetPassword",
    "validateToken"
  ]
}

❌ Design to Avoid:

{
  "name": "User Management Tool",
  "description": "Handles users, orders, payments, notifications, and all other functions",
  "methods": [
    "login", "createOrder", "sendEmail", "processPayment"
  ]
}

2. Interface Stability​

Design stable input/output interfaces and avoid frequent breaking changes.

Version Compatibility Strategy:

  • Provide default values when adding new fields
  • Maintain backward compatibility when deprecating fields
  • Bump the major version number for significant changes
{
  "inputSchema": {
    "type": "object",
    "properties": {
      "userId": {
        "type": "string",
        "title": "User ID"
      },
      "includeProfile": {
        "type": "boolean",
        "title": "Include Details",
        "default": false  // New fields should have default values
      },
      "format": {
        "type": "string",
        "title": "Return Format",
        "enum": ["json", "xml"],
        "default": "json",
        "deprecated": false  // Mark deprecation status
      }
    }
  }
}

3. Error Handling Mechanism​

Implement comprehensive error handling with user-friendly error messages.

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "success": {
        "type": "boolean",
        "title": "Execution Status"
      },
      "data": {
        "type": "object",
        "title": "Response Data"
      },
      "error": {
        "type": "object",
        "title": "Error Information",
        "properties": {
          "code": {
            "type": "string",
            "title": "Error Code"
          },
          "message": {
            "type": "string", 
            "title": "Error Description"
          },
          "details": {
            "type": "object",
            "title": "Details"
          }
        }
      }
    }
  }
}

Schema Design Best Practices​

1. Clear Naming Conventions​

Use meaningful, consistent naming conventions:

{
  "properties": {
    // ✅ Clear naming
    "userId": {"type": "string", "title": "User ID"},
    "userName": {"type": "string", "title": "Username"},
    "userEmail": {"type": "string", "title": "User Email"},
    
    // ❌ Naming to avoid
    "id": {"type": "string"},  // Not specific enough
    "data": {"type": "object"},  // Too generic
    "temp": {"type": "string"}  // Temporary naming
  }
}

2. Detailed Field Descriptions​

Provide clear descriptions and usage instructions for each field:

{
  "properties": {
    "timeout": {
      "type": "number",
      "title": "Timeout",
      "description": "API request timeout in milliseconds. Recommended to set between 30000-60000",
      "minimum": 1000,
      "maximum": 300000,
      "default": 30000
    },
    "retryPolicy": {
      "type": "object",
      "title": "Retry Policy",
      "description": "Retry configuration when a request fails. Set to null to disable retries",
      "properties": {
        "maxAttempts": {
          "type": "number",
          "title": "Max Retry Attempts",
          "description": "Maximum number of retries after failure; 0 means no retries",
          "minimum": 0,
          "maximum": 10,
          "default": 3
        }
      }
    }
  }
}

3. Reasonable Validation Rules​

Add appropriate validation rules without being overly restrictive:

{
  "properties": {
    "email": {
      "type": "string",
      "title": "Email Address",
      "format": "email",
      "pattern": "^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\\.[a-zA-Z]{2,}$"
    },
    "phoneNumber": {
      "type": "string", 
      "title": "Phone Number",
      "pattern": "^1[3-9]\\d{9}$",
      "description": "China mainland mobile phone number format"
    },
    "age": {
      "type": "integer",
      "title": "Age",
      "minimum": 0,
      "maximum": 150
    }
  }
}

4. Proper Use of Port Identification​

Correctly use the isPort identifier to distinguish between port parameters and configuration parameters:

{
  "inputSchema": {
    "type": "object",
    "properties": {
      // Workflow connection ports
      "inputData": {
        "type": "object",
        "title": "Input Data",
        "isPort": true,
        "description": "Data from upstream nodes"
      },
      "filterCondition": {
        "type": "string",
        "title": "Filter Condition", 
        "isPort": true,
        "description": "Data filter condition"
      },
      
      // Configuration parameters
      "outputFormat": {
        "type": "string",
        "title": "Output Format",
        "isPort": false,
        "enum": ["json", "csv", "xml"],
        "default": "json"
      }
    }
  }
}

Configuration Management Best Practices​

1. Layered Configuration Design​

Properly differentiate between operator-level and method-level configuration:

{
  // Operator-level configuration - globally shared
  "configuration": {
    "schema": {
      "properties": {
        "serverUrl": {
          "type": "string",
          "title": "Server URL",
          "description": "Base URL of the API server"
        },
        "globalTimeout": {
          "type": "number", 
          "title": "Global Timeout",
          "default": 30000
        }
      }
    }
  },
  
  // Method-level configuration - specific to a method
  "methods": [{
    "configuration": {
      "schema": {
        "properties": {
          "endpoint": {
            "type": "string",
            "title": "Endpoint Path",
            "description": "Specific endpoint path relative to the server URL"
          },
          "method": {
            "type": "string",
            "title": "HTTP Method",
            "enum": ["GET", "POST", "PUT", "DELETE"]
          }
        }
      }
    }
  }]
}

2. Sensitive Information Handling​

Handle sensitive configuration information properly:

{
  "systemConfiguration": {
    "schema": {
      "properties": {
        "apiKey": {
          "type": "string",
          "title": "API Key",
          "format": "password",  // Mark as sensitive information
          "description": "Key used for API authentication"
        },
        "databaseUrl": {
          "type": "string",
          "title": "Database Connection",
          "format": "password",
          "description": "Database connection string"
        }
      }
    }
  }
}

3. Environment-Specific Configuration​

Support configuration for different environments:

{
  "configuration": {
    "schema": {
      "properties": {
        "environment": {
          "type": "string",
          "title": "Runtime Environment",
          "enum": ["development", "staging", "production"],
          "default": "production"
        },
        "debugMode": {
          "type": "boolean",
          "title": "Debug Mode",
          "default": false,
          "description": "When enabled, outputs detailed debug information"
        }
      }
    }
  }
}

Performance Optimization​

1. Caching Strategy​

Implement caching mechanisms for appropriate operations:

{
  "configuration": {
    "schema": {
      "properties": {
        "caching": {
          "type": "object",
          "title": "Cache Configuration",
          "properties": {
            "enabled": {
              "type": "boolean",
              "title": "Enable Caching",
              "default": false
            },
            "ttlSeconds": {
              "type": "number",
              "title": "Cache Duration",
              "description": "Cache validity period in seconds",
              "default": 3600,
              "minimum": 60,
              "maximum": 86400
            },
            "maxSize": {
              "type": "number",
              "title": "Cache Size",
              "description": "Maximum number of cached entries",
              "default": 1000,
              "minimum": 10
            }
          }
        }
      }
    }
  }
}

2. Timeout and Retry​

Set reasonable timeout and retry policies:

{
  "configuration": {
    "schema": {
      "properties": {
        "timeout": {
          "type": "number",
          "title": "Request Timeout",
          "description": "Timeout for a single request in milliseconds",
          "default": 30000,
          "minimum": 1000,
          "maximum": 300000
        },
        "retryPolicy": {
          "type": "object",
          "title": "Retry Policy",
          "properties": {
            "maxAttempts": {
              "type": "number",
              "title": "Max Retry Attempts",
              "default": 3,
              "minimum": 0,
              "maximum": 10
            },
            "backoffMultiplier": {
              "type": "number",
              "title": "Backoff Multiplier",
              "description": "Delay multiplier for each retry",
              "default": 2.0,
              "minimum": 1.0
            },
            "initialDelayMs": {
              "type": "number",
              "title": "Initial Delay",
              "description": "Delay before the first retry in milliseconds",
              "default": 1000,
              "minimum": 100
            }
          }
        }
      }
    }
  }
}

3. Resource Limits​

Set reasonable resource limits for container-type operators:

{
  "systemConfiguration": {
    "schema": {
      "properties": {
        "resources": {
          "type": "object",
          "title": "Resource Limits",
          "properties": {
            "memory": {
              "type": "string",
              "title": "Memory Limit",
              "default": "512Mi",
              "pattern": "^\\d+[KMGT]i?$"
            },
            "cpu": {
              "type": "string", 
              "title": "CPU Limit",
              "default": "0.5",
              "pattern": "^\\d+(\\.\\d+)?$"
            },
            "timeout": {
              "type": "number",
              "title": "Execution Timeout",
              "description": "Maximum container execution time in seconds",
              "default": 300,
              "minimum": 10,
              "maximum": 3600
            }
          }
        }
      }
    }
  }
}

Security Best Practices​

1. Input Validation​

Strictly validate all input data:

{
  "inputSchema": {
    "type": "object",
    "properties": {
      "sqlQuery": {
        "type": "string",
        "title": "SQL Query",
        "pattern": "^SELECT\\s+.*",  // Only allow SELECT statements
        "maxLength": 1000,
        "description": "Only SELECT query statements are supported"
      },
      "filePath": {
        "type": "string",
        "title": "File Path",
        "pattern": "^[a-zA-Z0-9/._-]+$",  // Restrict file path characters
        "description": "File path cannot contain special characters"
      }
    }
  }
}

2. Access Control​

Implement appropriate access controls:

{
  "systemConfiguration": {
    "schema": {
      "properties": {
        "accessControl": {
          "type": "object",
          "title": "Access Control",
          "properties": {
            "allowedRoles": {
              "type": "array",
              "title": "Allowed Roles",
              "items": {"type": "string"},
              "default": ["user"]
            },
            "requireAuthentication": {
              "type": "boolean",
              "title": "Require Authentication",
              "default": true
            }
          }
        }
      }
    }
  }
}

3. Audit Logging​

Record audit logs for important operations:

{
  "outputSchema": {
    "type": "object",
    "properties": {
      "result": {
        "type": "object",
        "title": "Execution Result"
      },
      "auditLog": {
        "type": "object",
        "title": "Audit Log",
        "properties": {
          "operationId": {"type": "string", "title": "Operation ID"},
          "userId": {"type": "string", "title": "User ID"},
          "timestamp": {"type": "string", "title": "Operation Time"},
          "action": {"type": "string", "title": "Action Type"},
          "resource": {"type": "string", "title": "Affected Resource"}
        }
      }
    }
  }
}

Testing and Quality Assurance​

1. Unit Tests​

Write comprehensive test cases for operators:

{
  "testCases": [
    {
      "name": "Normal User Query",
      "input": {
        "userId": "12345",
        "includeProfile": true
      },
      "expectedOutput": {
        "success": true,
        "data": {
          "id": "12345",
          "name": "John Doe"
        }
      }
    },
    {
      "name": "User Not Found",
      "input": {
        "userId": "99999"
      },
      "expectedOutput": {
        "success": false,
        "error": {
          "code": "USER_NOT_FOUND",
          "message": "User not found"
        }
      }
    }
  ]
}

2. Integration Tests​

Test operators in actual workflows:

{
  "integrationTests": [
    {
      "workflow": "User Data Processing Flow",
      "steps": [
        "Data Input → User Query Operator → Data Transform Operator → Result Output"
      ],
      "testData": {
        "userIds": ["1", "2", "3"]
      },
      "expectedResults": {
        "processedUsers": 3,
        "errors": 0
      }
    }
  ]
}

3. Performance Tests​

Verify operator performance under high load:

{
  "performanceTests": [
    {
      "name": "Concurrent User Queries",
      "concurrency": 100,
      "duration": "60s",
      "expectedMetrics": {
        "averageResponseTime": "< 500ms",
        "errorRate": "< 1%",
        "throughput": "> 200 req/s"
      }
    }
  ]
}

Documentation and Maintenance​

1. Complete Documentation​

Write detailed usage documentation for operators:

# User Management Tool

## Overview
The User Management Tool provides query, create, update, and delete operations for user information.

## Method List

### getUserInfo - Get User Information
Get detailed user information by user ID.

**Input Parameters:**
- `userId` (string, required): Unique user identifier
- `includeProfile` (boolean, optional): Whether to include detailed profile, defaults to false

**Output Results:**
- `user` (object): User information object
- `metadata` (object): Query metadata

**Usage Example:**
```json
{
  "userId": "12345",
  "includeProfile": true
}

Error Handling:

  • USER_NOT_FOUND: User does not exist
  • INVALID_USER_ID: Invalid user ID format
  • ACCESS_DENIED: Access permission denied

### 2. Version Changelog

Maintain a detailed version update log:

```markdown
# Changelog

## v1.2.0 (2024-01-15)
### Added
- Batch user query method
- User avatar upload feature

### Improved
- Optimized user query performance, reducing response time by 30%
- Enhanced error message detail

### Fixed
- Fixed regex issue in user email validation
- Resolved data race condition in concurrent queries

## v1.1.0 (2024-01-01)
### Added
- User permission validation
- User data caching

### Changed
- Adjusted user ID format validation rules (backward compatible)

3. Monitoring and Alerts​

Set up monitoring for key metrics:

{
  "monitoring": {
    "metrics": [
      {
        "name": "response_time",
        "description": "Operator response time",
        "threshold": "500ms",
        "alertLevel": "warning"
      },
      {
        "name": "error_rate", 
        "description": "Error rate",
        "threshold": "5%",
        "alertLevel": "critical"
      },
      {
        "name": "throughput",
        "description": "Processing throughput",
        "threshold": "100 req/min",
        "alertLevel": "info"
      }
    ]
  }
}

Common Issues and Solutions​

1. Performance Issues​

Problem: Operator response time is too long Solutions:

  • Enable caching mechanism
  • Optimize database queries
  • Increase timeout and retry configuration
  • Consider asynchronous processing

2. Compatibility Issues​

Problem: New operator version is incompatible with existing workflows Solutions:

  • Maintain backward-compatible interface design
  • Use version number management
  • Provide migration guides
  • Support multiple versions running simultaneously

3. Security Issues​

Problem: Sensitive information leakage Solutions:

  • Use system configuration to store sensitive information
  • Implement appropriate access controls
  • Add audit logging
  • Conduct regular security reviews