約束元數據系統

目的：用於確定性 AI 生成、CLI 驗證及 Terraform 架構強制執行的全面約束元數據。

擴展名：x-f5xc-constraints 版本：3.3.0 狀態：生產環境 使用者：AI 助理、CLI 工具、Terraform 提供者、IDE 擴展、API 驗證器

---

目錄

1. 概覽
2. 擴展結構
3. 約束類型
4. 自然語言描述
5. 驗證範例
6. 信心分數
7. 探索整合
8. 工具整合指南

---

概覽

x-f5xc-constraints 擴展提供關於欄位驗證約束的確定性知識，實現以下功能：

• AI 助理：無需使用者提供約束詳細資訊即可生成有效配置
• CLI 工具：提供精確的輸入提示、驗證及錯誤訊息
• Terraform：在計劃階段而非套用階段強制執行約束
• IDE 擴展：即時驗證與自動完成建議
• API 驗證器：提交前驗證以減少 API 錯誤

覆蓋統計

• 所有 F5 XC API 規格中共 9,851 個約束
• 50 種以上模式類型（字串、陣列、數值）
• 高優先欄位（名稱、連接埠、識別碼）具有 95% 信心度
• 三層調和機制：EXISTING > DISCOVERY > INFERRED

---

擴展結構

頂層欄位

{
  "x-f5xc-constraints": {
    "constraintType": "string|array|number|object",
    "deterministic": true,
    "category": "length|size|range|pattern|character|format",

    "minLength": 1,
    "maxLength": 63,
    "pattern": "^[a-z0-9]+$",

    "metadata": {
      "source": "discovery|inferred|explicit",
      "confidence": 0.95,
      "category": "naming",
      "validatedAt": "2026-01-19T12:00:00Z"
    }
  }
}

欄位描述

欄位	類型	描述
constraintType	string	資料類型（string、array、number、object）
deterministic	boolean	高信心度旗標（信心度 >= 0.9），供 AI 生成使用
category	string	用於分組與報告的約束類別
（約束鍵）	各類型	扁平化於頂層的類型專屬約束鍵（例如 minLength、maxItems、minimum）
metadata	object	來源追蹤、信心度、驗證時間戳記

---

約束類型

字串約束

{
  "constraintType": "string",
  "category": "naming",
  "minLength": 1,
  "maxLength": 63,
  "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
  "characterSet": {
    "allowed": "[a-z0-9-]",
    "restricted": "[^a-z0-9-]",
    "required": "[a-z0-9]",
    "description": "Lowercase alphanumeric with hyphens, not at start/end"
  },
  "format": "dns-label",
  "formatDescription": "RFC 1123 DNS label: lowercase, alphanumeric, hyphens allowed but not at start/end",
  "byteLength": {
    "min": 1,
    "max": 63
  },
  "validation": {
    "rfc": "RFC 1123",
    "standard": "Kubernetes resource naming"
  },
  "metadata": {
    "source": "inferred",
    "confidence": 0.95
  },
  "deterministic": true
}

支援的格式

格式	描述	範例
dns-label	RFC 1123 DNS 標籤（1-63 個字元）	my-service
fqdn	完整網域名稱	api.example.com
email	RFC 5322 電子郵件地址	user@example.com
url	RFC 3986 URI/URL	https://example.com/api
ipv4	IPv4 地址	192.168.1.1
ipv6	IPv6 地址	2001:db8::1
uuid	RFC 4122 UUID	550e8400-e29b-41d4-a716-446655440000
date-time	ISO 8601 時間戳記	2026-01-19T12:00:00Z
date	ISO 8601 日期	2026-01-19
time	ISO 8601 時間	12:00:00
json	JSON 字串（可解析）	{"key": "value"}
yaml	YAML 字串（可解析）	key: value
base64	Base64 編碼字串	SGVsbG8gV29ybGQ=
hex	十六進位字串	48656c6c6f
mac-address	MAC 地址	00:1A:2B:3C:4D:5E
phone	E.164 電話號碼	+1-555-123-4567

陣列約束

{
  "constraintType": "array",
  "category": "collection",
  "minItems": 1,
  "maxItems": 50,
  "uniqueItems": true,
  "metadata": {
    "source": "inferred",
    "confidence": 0.90
  },
  "deterministic": true
}

數值約束

{
  "constraintType": "number",
  "category": "range",
  "minimum": 1,
  "maximum": 65535,
  "multipleOf": 1,
  "exclusiveMinimum": false,
  "exclusiveMaximum": false,
  "metadata": {
    "source": "inferred",
    "confidence": 0.99
  },
  "deterministic": true
}

---

自然語言描述

字串格式約束

DNS 標籤 （format: "dns-label"）：

• DNS 標籤名稱必須為 1-63 個小寫英數字元
• 允許連字號，但不得出現在開頭或結尾（RFC 1123）
• 範例：my-service、api-gateway、lb-prod-01

電子郵件地址 （format: "email"）：

• 電子郵件地址必須符合 RFC 5322 規範
• 最多 254 個字元
• 範例：admin@example.com、api+webhook@service.io

完整網域名稱 （format: "fqdn"）：

• 完整網域名稱必須為 1-253 個字元
• 由點分隔的 DNS 標籤組成
• 範例：api.example.com、service.production.internal

URL （format: "url"）：

• URL 必須為符合 RFC 3986 的有效 URI
• 必須包含協定（http/https）
• 範例：https://api.example.com/v1、http://localhost:8080

IPv4 地址 （format: "ipv4"）：

• IPv4 地址必須使用點分十進位表示法
• 範例：192.168.1.1、10.0.0.1

UUID （format: "uuid"）：

• UUID 必須遵循 RFC 4122 格式
• 範例：550e8400-e29b-41d4-a716-446655440000

時間戳記 （format: "date-time"）：

• 時間戳記必須為 ISO 8601 格式
• 範例：2026-01-19T12:00:00Z、2026-01-19T12:00:00+00:00

數值約束

連接埠號碼：

• 連接埠號碼必須為 1 至 65535 之間的整數
• 標準連接埠：80（HTTP）、443（HTTPS）、22（SSH）

VLAN ID：

• VLAN ID 必須為 1 至 4094 之間的整數（802.1Q 標準）

逾時時間：

• 逾時時間必須為 1 至 3600 秒（最長 1 小時）

陣列約束

來源池：

• 來源池陣列至少需要 1 個項目，最多 50 個項目
• 每個項目必須唯一

標籤：

• 標籤陣列允許 0 至 100 個項目
• 項目無需唯一

---

驗證範例

範例 1：DNS 標籤名稱驗證

約束：

{
  "constraintType": "string",
  "minLength": 1,
  "maxLength": 63,
  "pattern": "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$",
  "format": "dns-label",
  "deterministic": true
}

有效值：

• ✅ my-service
• ✅ api-gateway
• ✅ lb-prod-01
• ✅ web

無效值：

• ❌ My-Service（不允許大寫字母）
• ❌ -my-service（連字號不得出現在開頭）
• ❌ my-service-（連字號不得出現在結尾）
• ❌ my_service（不允許底線）
• ❌ this-is-a-very-long-name-that-exceeds-the-sixty-three-character-limit（名稱過長）

範例 2：連接埠號碼驗證

約束：

{
  "constraintType": "number",
  "minimum": 1,
  "maximum": 65535,
  "deterministic": true
}

有效值：

• ✅ 80（HTTP）
• ✅ 443（HTTPS）
• ✅ 8080（常用替代 HTTP 連接埠）
• ✅ 65535（最大連接埠號）

無效值：

• ❌ 0（低於最小值）
• ❌ 65536（超過最大值）
• ❌ -1（負數）
• ❌ "80"（字串，非數值）

範例 3：陣列大小驗證

約束：

{
  "constraintType": "array",
  "minItems": 1,
  "maxItems": 50,
  "uniqueItems": true,
  "deterministic": true
}

有效值：

• ✅ ["origin-1"]（1 個項目）
• ✅ ["origin-1", "origin-2", "origin-3"]（3 個項目，全部唯一）

無效值：

• ❌ []（低於最小值）
• ❌ ["origin-1", "origin-1"]（重複項目）
• ❌ [含 51 個項目的陣列]（超過最大值）

---

信心分數

分數解讀

範圍	解讀	使用方式
0.90-1.00	高信心度	啟用確定性旗標，可用於 AI 生成
0.70-0.89	中等信心度	建議性，建議由使用者確認
0.50-0.69	低信心度	僅供參考，需要使用者驗證
< 0.50	極低	不納入約束

確定性旗標

deterministic 布林旗標在以下情況下設為 true：

• 信心分數 >= 0.9
• 模式已針對探索資料進行驗證，或
• 模式符合既定標準（RFC、ISO 等）

在 AI 生成中的使用方式：

if constraint.get("deterministic"):
    # 自動生成值，無需詢問使用者
    value = generate_from_pattern(constraint)
else:
    # 提示使用者輸入並提供約束提示
    value = prompt_user_with_hints(constraint)

---

探索整合

來源優先順序

約束使用三層優先順序進行調和：

1. EXISTING（信心度：1.0）

   • 在原始 OpenAPI 規格中明確設定
   • 永不被覆蓋

2. DISCOVERY（信心度：0.99）

   • 從即時 F5 XC API 回應中提取
   • 包含來自 x-ves-validation-rules 的驗證規則
   • 覆蓋推斷約束

3. INFERRED（信心度：0.50-0.95）

   • 從欄位名稱進行模式比對
   • 優先順序最低，可被探索或明確約束覆蓋

探索資料來源

探索約束從以下來源提取：

1. x-ves-validation-rules：原生 F5 驗證擴展

   • ves.io.schema.rules.string.max_len → maxLength
   • ves.io.schema.rules.string.pattern → pattern
   • ves.io.schema.rules.repeated.max_items → maxItems

2. 錯誤目錄：指出約束違規的 API 錯誤訊息

   • “name must be 1-63 characters” → minLength/maxLength
   • “port must be between 1 and 65535” → minimum/maximum

3. 回應驗證：展示有效值的成功 API 回應

   • 觀察到的值範圍
   • 實際格式模式

---

工具整合指南

AI 助理整合

生成有效的資源名稱：

def generate_resource_name(schema_property):
    constraints = schema_property.get("x-f5xc-constraints", {})

    if not constraints.get("deterministic"):
        # 詢問使用者輸入名稱
        return prompt_user("Enter resource name: ")

    # 自動生成
    pattern = constraints.get("pattern")
    max_len = constraints.get("maxLength", 63)

    # 生成符合模式的有效名稱
    return generate_dns_label(max_length=max_len)

CLI 工具整合

提供輸入驗證：

def validate_cli_input(field_name, user_value, constraints):
    if not constraints:
        return True, None

    # 檢查長度（約束鍵位於頂層）
    if "minLength" in constraints and len(user_value) < constraints["minLength"]:
        return False, f"{field_name} must be at least {constraints['minLength']} characters"

    if "maxLength" in constraints and len(user_value) > constraints["maxLength"]:
        return False, f"{field_name} must be at most {constraints['maxLength']} characters"

    # 檢查模式
    if "pattern" in constraints:
        import re
        if not re.match(constraints["pattern"], user_value):
            char_set = constraints.get("characterSet", {})
            desc = char_set.get("description", "valid format")
            return False, f"{field_name} must match {desc}"

    return True, None

Terraform 提供者整合

架構生成：

func generateTerraformSchema(property map[string]interface{}) *schema.Schema {
    constraints := property["x-f5xc-constraints"].(map[string]interface{})
    s := &schema.Schema{
        Type:     schema.TypeString,
        Required: true,
    }

    // 約束鍵位於頂層（無巢狀 "string" 包裝）
    if minLen, ok := constraints["minLength"].(float64); ok {
        s.ValidateDiagFunc = validation.StringLenBetween(int(minLen), int(constraints["maxLength"].(float64)))
    }

    if pattern, ok := constraints["pattern"].(string); ok {
        charSet := constraints["characterSet"].(map[string]interface{})
        s.ValidateDiagFunc = validation.StringMatch(regexp.MustCompile(pattern),
            charSet["description"].(string))
    }

    return s
}

IDE 擴展整合

自動完成與驗證：

function provideCompletions(field: FieldInfo): CompletionItem[] {
    const constraints = field.schema['x-f5xc-constraints'];
    if (!constraints) return [];

    const items: CompletionItem[] = [];

    // 新增格式專屬的自動完成項目
    if (constraints.format === 'dns-label') {
        items.push({
            label: 'my-service',
            detail: 'Example DNS label',
            kind: CompletionItemKind.Value
        });
    }

    // 新增驗證提示
    if (constraints.deterministic) {
        items.push({
            label: '✨ Auto-generate',
            detail: 'Generate valid value automatically',
            kind: CompletionItemKind.Function,
            command: { command: 'f5xc.generateValue', arguments: [field] }
        });
    }

    return items;
}

---

附錄：約束模式目錄

高信心度模式（0.95-0.99）

模式	欄位名稱正規表達式	約束類型	範例
DNS 標籤	\bname$	字串（1-63 個字元，dns-label）	my-service
命名空間	\bnamespace$	字串（1-63 個字元，dns-label）	production
連接埠	\bport$	數值（1-65535）	443
VLAN ID	\b(vlan)?_?id$	數值（1-4094）	100
UUID	\buuid$	字串（36 個字元，uuid 格式）	550e8400-...
電子郵件	\bemail$	字串（最多 254 個字元，email）	user@example.com
時間戳記	\b(timestamp|created_at|updated_at)$	字串（ISO 8601）	2026-01-19T12:00:00Z

中等信心度模式（0.80-0.94）

模式	欄位名稱正規表達式	約束類型	範例
使用者名稱	\b(user|username)$	字串（1-64 個字元，英數字）	admin
顯示名稱	\b(display_?)?name$	字串（1-256 個字元，自由文字）	My Service
描述	\b(comment|description|note)$	字串（最多 4096 個字元）	Service description
路徑	\bpath$	字串（最多 2048 個字元）	/api/v1/resources

---

支援與意見回饋

• 問題回報：在 https://github.com/f5-sales-demo/api-specs-enriched/issues 回報約束準確性問題
• 文件：完整 API 文件請參閱 https://f5-sales-demo.github.io/api-specs-enriched/
• MCP 整合：MCP 伺服器整合範例請參閱 f5xc-api-mcp 儲存庫

---

版本：3.3.0 最後更新：2026-01-19 已調和約束數：9,851 模式覆蓋率：50 種以上類型