範本的上下文

當您生成程式碼時，Restorm 會把 您的整個設計 以一個 ctx 物件的形式傳給 範本。您的模型、您的列舉、您的路由，尤其是 它們的意圖（searchable、PII、 cache，以及模型的整個運行輪廓：volumetry、accessPattern、traffic、freshness、 sensitivity、retention）都在其中 —— 範本讀取它們來決定生成什麼。為此不需要一個 變數：您已經在設計中輸入的資訊可以直接使用。

ctx 的形狀

ctx
├─ design        # name, version, description, basePath, defaultAuth, vars
├─ enums[]       # name, description, values[]
├─ models[]      # name, description, inherits, identifier, timestamps, softDelete,
│                # volumetry, accessPattern, traffic, freshness, sensitivity,
│                # retention, properties[], allProperties[], examples[], vars
└─ groups[]      # name, basePath, versionPrefix, headers[], routes[]
     └─ routes[] # method, path, fullPath, params[], body, responses[],
                 # auth, pagination, cacheSeconds, idempotent, deprecated, vars

參照透過名稱進行（從不透過內部識別碼）：property.enum 是列舉的名稱， property.references.model 是所指向模型的名稱，model.inherits 是父層的名稱。 在一個模型上，properties[] 列出它 自有的 屬性（用於類型宣告），而 allProperties[] 列出 自有 + 繼承、被展平的 屬性（用於一個完整實例：範例 資料、SQL 欄、請求主體）。

讀取一個旗標：黃金法則

布林旗標 只有在被啟用時 才出現在 ctx 中。引擎以 StrictUndefined 渲染： 因此必須 測試鍵的存在，絕不測試它的值。

{# ✅ correct — on teste la présence #}
{% if 'searchable' in p %}INDEX({{ p['name'] }}){% endif %}

{# ❌ faux — lève une erreur quand le flag est absent #}
{% if p.searchable %}…{% endif %}

只有 property.required（布林）和 route.auth（列舉）始終 存在。其他布林 旗標是「存在 = 真」；帶 值 的欄位（volumetry、運行輪廓、cache……）在被填寫時 帶有它們的值，否則不存在 —— 同樣的存在規則。

在 屬性 上	在 模型 上	在 路由 上
readOnly · writeOnly · nullable	timestamps · softDelete（布林）	idempotent · deprecated（布林）
unique · searchable · immutable · pii	運行輪廓（值）：volumetry · accessPattern · traffic · freshness · sensitivity · retention	cacheSeconds（數字） · pagination（物件）

一個模型的 運行輪廓 的值：accessPattern （readHeavy / writeHeavy / balanced / appendOnly）、traffic （low / medium / high）、freshness（strong / shortCache / longCache）、 sensitivity（public / internal / confidential / pii）、retention （permanent / archivable / ephemeral）、volumetry（hundreds / tenThousands / millions）。

Note

始終以方括號寫法存取鍵（p['name']、route['vars']）：上下文是作為簡單的字典 傳遞的，因此 example.values 會呼叫字典的 方法 values 而不是您的鍵。參見 可移植性規則。

範例：快取讀取需求高的資料

有兩種情況，取決於該資訊是否已經存在於設計中。

a) 設計已經帶有該資訊

如果您在一條路由上填寫了一個 快取時長，它會到達 route['cacheSeconds']； route['idempotent'] 告訴您它可以安全地快取（唯讀）：

{% for group in ctx['groups'] %}
{% for route in group['routes'] %}
{% if 'cacheSeconds' in route and 'idempotent' in route %}
// {{ route['method'] }} {{ route['fullPath'] }}
app.use("{{ route['fullPath'] }}", cache({{ route['cacheSeconds'] }}));
{% endif %}
{% endfor %}
{% endfor %}

b)「讀取需求高」是模型的一個原生欄位

不需要變數：「讀取需求高」直接就是模型的 存取輪廓。在模型的設定中、運行輪廓 群組裡，您選擇 Lecture dominante（以讀為主）—— 範本在 model['accessPattern'] 中 讀取它。把它與 model['freshness']（對新鮮度的容忍度）結合，來決定是否要快取， 以及快取多久：

{% for model in ctx['models'] %}
{% if model['accessPattern'] == 'readHeavy' and model['freshness'] != 'strong' %}
{% set ttl = 3600 if model['freshness'] == 'longCache' else 60 %}
registerCache("{{ model['name'] }}", {{ ttl }});   // cache activé ({{ ttl }}s)
{% endif %}
{% endfor %}

注意 != 'strong' 這個測試：一個以讀為主 但 要求強一致性的模型 不應 被 快取。這正是把兩個意圖在設計中並排放置的全部價值所在。

請把生成變數留給設計尚未承載的東西（一個範本自身的 設定）：業務意圖 —— volumetry、accessPattern、traffic、freshness、sensitivity、 retention —— 是模型的 原生欄位。

完整的契約

這個上下文是受版本控制的（ctx['contextVersion']），並由一份隨應用程式儲存庫一起 交付的 JSON-Schema（docs/contributing/design-codegen-context.schema.json）詳盡 描述 —— 把它複製到您的範本中，好讓它的 CI 驗證參考上下文。一個 AI 代理程式透過 MCP 工具 get_design_template_contract 即時獲得同樣的契約。