 codescan handlers 包維護指南：SimpleSchema 與 full-Schema 雙分派機制源碼解析)
Podman 倉庫內(nèi) codescan handlers 包維護指南SimpleSchema 與 full-Schema 雙分派機制源碼解析【免費下載鏈接】podmanPodman: A tool for managing OCI containers and pods.項目地址: https://gitcode.com/gh_mirrors/po/podman本文基于 Podman 倉庫test/tools/vendor下 vendored 的 go-openapi/codescanv0.35.1內(nèi)部handlers包維護文檔handlers/README.md圍繞其核心主題展開codescan 如何通過共享的 grammar Walker 回調(diào)把 Go 源碼注釋中的 swagger 注解寫入 OAS v2Swagger 2.0的參數(shù)、響應(yīng)頭、items 鏈與完整 Schema 四類目標對象。讀完本文你將掌握該包SimpleSchema與full-Schema兩族分派器的設(shè)計差異、每個 Walker 回調(diào)的載荷約定、errSink錯誤傳播契約、collectionFormat容錯回退、required:的例外處理、vendor 擴展落地路徑以及enum:覆蓋時對過期文檔清理的細節(jié)。背景說明codescan 是 go-swagger 生態(tài)中負責從 Go 注釋掃描生成 OpenAPI/Swagger 文檔的掃描器它以internal包形式被 vendored 進 Podman 倉庫見 test/tools/go.mod服務(wù)于 Podman 的測試工具鏈。本文所有源碼引用均指向該 vendored 目錄與分析對象同一倉庫、同一版本。目錄兩族分派器SimpleSchema 與 full-SchemaWalker 回調(diào)載荷約定Raw 回調(diào)的 errSink 契約參數(shù)硬失敗、響應(yīng)頭靜默collectionFormat 的寬松回退保留作者意圖SimpleSchema 關(guān)鍵字白名單與 required 例外vendor 擴展通過 AddExtension 落地enum 覆蓋導(dǎo)致的陳舊 x-go-enum-desc 清理已記錄的待辦事項參考閱讀兩族分派器SimpleSchema 與 full-Schemahandlers包導(dǎo)出了兩族分派器對應(yīng) OAS v2 中兩種不同的驗證語法面詳見 handlers/README.md §dispatch-surfaceSimpleSchema 族DispatchParamLevel0、DispatchHeaderLevel0、DispatchItemsLevel。三者圍繞單個Keyword.Name的 switch 展開把載荷通過ifaces.ValidationBuilder或ifaces.OperationValidationBuilder適配器寫入目標對象對應(yīng)paramValidations、headerValidations、items.Validations三個適配器。full-Schema 族DispatchSchemaLevel0、DispatchSchemaItemsLevel。它們在 SimpleSchema 的基礎(chǔ)上增加了一道checkShape門對關(guān)鍵字與已解析類型不匹配的情況發(fā)出CodeShapeMismatch診斷此外其 Bool 處理器支持跨目標寫入required:寫入enclosing.Required按名字索引discriminator:同理。形狀門與跨目標寫入是 full-Schema 族獨有的關(guān)注點與 SimpleSchema 族的接縫并不共享。SchemaOptions結(jié)構(gòu)體攜帶SimpleSchemaMode標志full-Schema 分派器用它來門控 full-Schema 專有關(guān)鍵字readOnly、discriminator對命中項發(fā)出CodeUnsupportedInSimpleSchema診斷同時在 SimpleSchema 模式下對required:靜默跳過參數(shù)層的required:由 SimpleSchema 分派在參數(shù)級別處理響應(yīng)頭根本不攜帶required:。具體實現(xiàn)可從 dispatch_simple.go 與 dispatch_schema.go 驗證例如DispatchParamLevel0組裝了 Number / Integer / BoolComposeBool(UniqueBool, paramRequiredBool)/ StringComposeString(PatternString, CollectionFormatString, UnsupportedSimpleSchemaString)/ Raw帶 errSink/ Extension 共六個回調(diào)槽位DispatchHeaderLevel0則去掉required:并把 errSink 置為 nilDispatchSchemaLevel0則使用schemaNumberHandler、schemaIntegerHandler、schemaBoolHandler、schemaStringHandler、schemaRawHandler這組帶形狀檢查的處理器。從調(diào)用側(cè)看這兩個家族在倉庫中的接線如下參數(shù)構(gòu)建器在 parameters/walker.go 調(diào)用handlers.DispatchParamLevel0并在 items 鏈上遞歸調(diào)用handlers.DispatchItemsLevelL83響應(yīng)構(gòu)建器在 responses/walker.go 調(diào)用DispatchHeaderLevel0與DispatchItemsLevel并在 responses/responses.go 等處調(diào)用DispatchSchemaLevel0。Walker 回調(diào)載荷約定各 Walker 回調(diào)的載荷約定詳見 handlers/README.md §walker-payloadsNumber / Integer / Bool 回調(diào)當詞法器拒絕了源值時會以零值載荷觸發(fā)此時解析器已經(jīng)發(fā)出CodeInvalid{Number,Integer,Boolean}診斷。消費者必須先通過pr.IsTyped()把關(guān)再寫入——本包內(nèi)所有輔助函數(shù)都在內(nèi)部做了這個把關(guān)。例如Number處理器handlers.go在!pr.IsTyped()時直接返回只有類型判定通過后才把maximum:/minimum:/multipleOf:路由到對應(yīng)的 Setter。String 回調(diào)攜帶原始值與pr.Value。對于pattern:消費者應(yīng)讀取pr.Value正則源碼而非格式化后的字符串以保證正則原樣抵達SetPattern。這正是PatternStringhandlers.go的實現(xiàn)方式——回調(diào)簽名雖然接收字符串參數(shù)但內(nèi)部讀取的是pr.Value。Raw 回調(diào)針對ShapeRawValue關(guān)鍵字default:、example:、enum:觸發(fā)從pr.Value讀取原始文本。Raw 回調(diào)的 errSink 契約參數(shù)硬失敗、響應(yīng)頭靜默Raw接受一個errSink func(error) bool參數(shù)用來控制default:/example:的強制類型轉(zhuǎn)換coercion錯誤如何傳播詳見 handlers/README.md §raw-errsinkerrSink nil靜默吞掉錯誤。響應(yīng)頭路徑采用這種姿態(tài)——響應(yīng)頭上格式錯誤的 default/example 不會導(dǎo)致構(gòu)建失敗。DispatchHeaderLevel0與DispatchItemsLevel都接入了errSinknil。errSink ! nil以第一個ParseValueFromSchema錯誤調(diào)用它。返回true會在同一次 Walker 調(diào)用中短路后續(xù)的Raw回調(diào)閉包內(nèi)的stopped標志返回false則繼續(xù)。DispatchParamLevel0接入的 sink 會捕獲第一個錯誤并返回true見 dispatch_simple.go因此參數(shù)上格式錯誤的default:/example:會被作為硬失敗向上冒泡給調(diào)用方。集成測試套件中的TestMalformed_DefaultInt/TestMalformed_ExampleInt覆蓋了這一端到端行為該測試位于 codescan 倉庫的集成測試中本 vendored 目錄內(nèi)可在 handlers/README.md 找到對應(yīng)指引。從實現(xiàn)看Raw處理器handlers.go通過閉包stopped標志實現(xiàn)短路一旦 errSink 返回true后續(xù)所有屬性都會被跳過。此外當 full-Schema 專有的 raw 關(guān)鍵字如externalDocs:出現(xiàn)在 SimpleSchema 站點時若diag非 nil 會發(fā)出CodeUnsupportedInSimpleSchema警告并丟棄該關(guān)鍵字。collectionFormat 的寬松回退保留作者意圖CollectionFormatString優(yōu)先嘗試 Walker 提供的類型化字符串當該值為空語法中封閉詞匯的 string-enum 拒絕了源值時回退到strings.TrimSpace(pr.Value)把原始值原樣寫入詳見 handlers/README.md §collection-format-fallback。OAS v2 規(guī)范定義了封閉詞匯csv/ssv/tsv/pipes/multi但 codescan 語法在這個位置有意保持寬松像pipe這樣拼寫錯誤的pipes會原樣往返到參數(shù)或 items 對象上。這樣做的目的是把源碼作者的意圖保留給下游工具由下游直接對照規(guī)范文本暴露校驗錯誤。注意CollectionFormatString是 SimpleSchema 專屬full-Schema 的Validations適配器不暴露SetCollectionFormat因為collectionFormat:不是 full-Schema 關(guān)鍵字。實現(xiàn)位于 handlers.go其簽名依賴ifaces.OperationValidationBuilder參數(shù)與響應(yīng)頭兩個適配器都實現(xiàn)了該接口。SimpleSchema 關(guān)鍵字白名單與 required 例外keywords.go中的simpleSchemaAllowed枚舉了 OAS v2 SimpleSchema 站點in ! body的參數(shù)、響應(yīng)頭以及二者內(nèi)部的 items 鏈上合法的語法關(guān)鍵字名其權(quán)威來源是 OAS v2 Parameter Object 與 Header Object 的 allowed-keyword 表詳見 handlers/README.md §simple-schema-keywords。完整白名單keywords.go關(guān)鍵字對應(yīng)的 SettermaximumSetMaximumminimumSetMinimummultipleOfSetMultipleOfminLength/maxLengthSetMinLength/SetMaxLengthpatternSetPatternminItems/maxItemsSetMinItems/SetMaxItemsuniqueSetUniquecollectionFormatSetCollectionFormatdefault/example/enumSetDefault/SetExample/SetEnumrequiredparamRequiredBool參數(shù)層特例見下Vendor 擴展x-*不在白名單中——它們由classify.IsAllowedExtension按名稱前綴門控見 classify/extension.goIsAllowedExtension判斷鍵名是否以x-或X-開頭。required:之所以被列入 SimpleSchema 白名單是因為它在參數(shù)站點是合法的作為參數(shù)級布爾值但在響應(yīng)頭上不合法。由此產(chǎn)生兩個后果參數(shù) walker 通過paramRequiredBool把required:直接寫到param.Required見 dispatch_simple.go——值落在參數(shù)對象上而非 schema 上full-Schema walkerschemaBoolHandler在SimpleSchemaMode下靜默跳過required:因為它的 full-Schema 目標是enclosing.Required[name]——對象級 required 數(shù)組——與 SimpleSchema 形態(tài)不匹配見 dispatch_schema.go。IsSimpleSchemaKeyword對 full-Schema 專有關(guān)鍵字readOnly、discriminator、$ref、allOf等和未知名稱返回false。以 SimpleSchema 模式接線的消費者用這個謂詞門控寫入并在命中時發(fā)出CodeUnsupportedInSimpleSchema診斷。這一機制在Integer處理器handlers.go中體現(xiàn)為識別min/maxLength:與min/maxItems:其余整型關(guān)鍵字即 full-Schema 專屬的minProperties:/maxProperties:通過isFullSchemaOnly判定后發(fā)出警告并丟棄。vendor 擴展通過 AddExtension 落地ExtensionTarget是Walker.Extension消費者寫入 vendor 擴展所需的最小接口面詳見 handlers/README.md §extensions。它被所有嵌入了VendorExtensible的oaispec對象實現(xiàn)Schema、Parameter、Header、Response、Operation等通過從嵌入結(jié)構(gòu)提升的AddExtension方法完成寫入。Extension返回一個回調(diào)handlers.go該回調(diào)先用classify.IsAllowedExtension過濾非x-*名稱再把類型化的擴展值寫到目標對象上。關(guān)鍵細節(jié)用戶手寫的擴展不受SkipExtensions選項門控——該選項只抑制掃描器派生的x-go-*鍵不影響作者意圖。需要寫入成功后附加副作用例如 schema 構(gòu)建器的refOverrideCollector標記收集器的消費者應(yīng)該用自定義回調(diào)包裹該輔助函數(shù)而不是直接復(fù)用。這一點也在全包范圍內(nèi)通過Extension(param)、Extension(header)、Extension(ps)三個接線點體現(xiàn)分別在參數(shù)、響應(yīng)頭與 schema 分派器中。enum 覆蓋導(dǎo)致的陳舊 x-go-enum-desc 清理SchemaValidations.SetEnum先把解析出的 enum 寫到 schema 上隨后調(diào)用clearStaleEnumDesc在存在x-go-enum-desc擴展時將其剝離并同步把Description中匹配的后綴去掉詳見 handlers/README.md §stale-enum-desc。背景該擴展由類型級的swagger:enum TypeName通道設(shè)置攜帶每個枚舉值的文檔文本。當字段級enum:注解覆蓋了繼承值后原有的按值文檔文本所描述的值已不在字段級 enum 中——文檔變得陳舊必須丟棄以免產(chǎn)生誤導(dǎo)。實現(xiàn)位于 dispatch_schema.goclearStaleEnumDesc通過resolvers.GetEnumDesc讀取擴展刪除resolvers.ExtEnumDesc鍵并用strings.TrimSuffix依次去掉描述中的枚舉說明后綴與尾部換行。已記錄的待辦事項維護文檔列出了兩個有意推遲的后續(xù)項詳見 handlers/README.md §quirks-opencollectionFormat:的寬松接受?；赝说皆甲址怯幸獗Ａ羝磳戝e誤的行為。未來可考慮增加嚴格模式選項當值超出 OAS v2 封閉詞匯時發(fā)出診斷同時保留當前寬松默認值以維持兼容性。items 分派上的SchemaOptions.SimpleSchemaMode。該選項出于對稱性被DispatchSchemaItemsLevel接受但目前不改變 items 級行為。若未來 items 分派需要與 level-0 相同的門控值得重新審視。參考閱讀handlers 包維護文檔本文主體SimpleSchema 族分派實現(xiàn)full-Schema 族分派實現(xiàn)共享 Walker 回調(diào)與適配器實現(xiàn)SimpleSchema 關(guān)鍵字白名單關(guān)鍵字語法定義上下文、別名與形狀參數(shù)構(gòu)建器對分派器的調(diào)用點響應(yīng)構(gòu)建器對分派器的調(diào)用點vendor 擴展鍵名判定【免費下載鏈接】podmanPodman: A tool for managing OCI containers and pods.項目地址: https://gitcode.com/gh_mirrors/po/podman創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考 Podman 倉庫內(nèi) codescan handlers 包維護指南：SimpleSchema 與 full-Schema 雙分派機制源碼解析
Podman 倉庫內(nèi) codescan handlers 包維護指南SimpleSchema 與 full-Schema 雙分派機制源碼解析【免費下載鏈接】podmanPodman: A tool for managing OCI containers and pods.項目地址: https://gitcode.com/gh_mirrors/po/podman本文基于 Podman 倉庫test/tools/vendor下 vendored 的 go-openapi/codescanv0.35.1內(nèi)部handlers包維護文檔handlers/README.md圍繞其核心主題展開codescan 如何通過共享的 grammar Walker 回調(diào)把 Go 源碼注釋中的 swagger 注解寫入 OAS v2Swagger 2.0的參數(shù)、響應(yīng)頭、items 鏈與完整 Schema 四類目標對象。讀完本文你將掌握該包SimpleSchema與full-Schema兩族分派器的設(shè)計差異、每個 Walker 回調(diào)的載荷約定、errSink錯誤傳播契約、collectionFormat容錯回退、required:的例外處理、vendor 擴展落地路徑以及enum:覆蓋時對過期文檔清理的細節(jié)。背景說明codescan 是 go-swagger 生態(tài)中負責從 Go 注釋掃描生成 OpenAPI/Swagger 文檔的掃描器它以internal包形式被 vendored 進 Podman 倉庫見 test/tools/go.mod服務(wù)于 Podman 的測試工具鏈。本文所有源碼引用均指向該 vendored 目錄與分析對象同一倉庫、同一版本。目錄兩族分派器SimpleSchema 與 full-SchemaWalker 回調(diào)載荷約定Raw 回調(diào)的 errSink 契約參數(shù)硬失敗、響應(yīng)頭靜默collectionFormat 的寬松回退保留作者意圖SimpleSchema 關(guān)鍵字白名單與 required 例外vendor 擴展通過 AddExtension 落地enum 覆蓋導(dǎo)致的陳舊 x-go-enum-desc 清理已記錄的待辦事項參考閱讀兩族分派器SimpleSchema 與 full-Schemahandlers包導(dǎo)出了兩族分派器對應(yīng) OAS v2 中兩種不同的驗證語法面詳見 handlers/README.md §dispatch-surfaceSimpleSchema 族DispatchParamLevel0、DispatchHeaderLevel0、DispatchItemsLevel。三者圍繞單個Keyword.Name的 switch 展開把載荷通過ifaces.ValidationBuilder或ifaces.OperationValidationBuilder適配器寫入目標對象對應(yīng)paramValidations、headerValidations、items.Validations三個適配器。full-Schema 族DispatchSchemaLevel0、DispatchSchemaItemsLevel。它們在 SimpleSchema 的基礎(chǔ)上增加了一道checkShape門對關(guān)鍵字與已解析類型不匹配的情況發(fā)出CodeShapeMismatch診斷此外其 Bool 處理器支持跨目標寫入required:寫入enclosing.Required按名字索引discriminator:同理。形狀門與跨目標寫入是 full-Schema 族獨有的關(guān)注點與 SimpleSchema 族的接縫并不共享。SchemaOptions結(jié)構(gòu)體攜帶SimpleSchemaMode標志full-Schema 分派器用它來門控 full-Schema 專有關(guān)鍵字readOnly、discriminator對命中項發(fā)出CodeUnsupportedInSimpleSchema診斷同時在 SimpleSchema 模式下對required:靜默跳過參數(shù)層的required:由 SimpleSchema 分派在參數(shù)級別處理響應(yīng)頭根本不攜帶required:。具體實現(xiàn)可從 dispatch_simple.go 與 dispatch_schema.go 驗證例如DispatchParamLevel0組裝了 Number / Integer / BoolComposeBool(UniqueBool, paramRequiredBool)/ StringComposeString(PatternString, CollectionFormatString, UnsupportedSimpleSchemaString)/ Raw帶 errSink/ Extension 共六個回調(diào)槽位DispatchHeaderLevel0則去掉required:并把 errSink 置為 nilDispatchSchemaLevel0則使用schemaNumberHandler、schemaIntegerHandler、schemaBoolHandler、schemaStringHandler、schemaRawHandler這組帶形狀檢查的處理器。從調(diào)用側(cè)看這兩個家族在倉庫中的接線如下參數(shù)構(gòu)建器在 parameters/walker.go 調(diào)用handlers.DispatchParamLevel0并在 items 鏈上遞歸調(diào)用handlers.DispatchItemsLevelL83響應(yīng)構(gòu)建器在 responses/walker.go 調(diào)用DispatchHeaderLevel0與DispatchItemsLevel并在 responses/responses.go 等處調(diào)用DispatchSchemaLevel0。Walker 回調(diào)載荷約定各 Walker 回調(diào)的載荷約定詳見 handlers/README.md §walker-payloadsNumber / Integer / Bool 回調(diào)當詞法器拒絕了源值時會以零值載荷觸發(fā)此時解析器已經(jīng)發(fā)出CodeInvalid{Number,Integer,Boolean}診斷。消費者必須先通過pr.IsTyped()把關(guān)再寫入——本包內(nèi)所有輔助函數(shù)都在內(nèi)部做了這個把關(guān)。例如Number處理器handlers.go在!pr.IsTyped()時直接返回只有類型判定通過后才把maximum:/minimum:/multipleOf:路由到對應(yīng)的 Setter。String 回調(diào)攜帶原始值與pr.Value。對于pattern:消費者應(yīng)讀取pr.Value正則源碼而非格式化后的字符串以保證正則原樣抵達SetPattern。這正是PatternStringhandlers.go的實現(xiàn)方式——回調(diào)簽名雖然接收字符串參數(shù)但內(nèi)部讀取的是pr.Value。Raw 回調(diào)針對ShapeRawValue關(guān)鍵字default:、example:、enum:觸發(fā)從pr.Value讀取原始文本。Raw 回調(diào)的 errSink 契約參數(shù)硬失敗、響應(yīng)頭靜默Raw接受一個errSink func(error) bool參數(shù)用來控制default:/example:的強制類型轉(zhuǎn)換coercion錯誤如何傳播詳見 handlers/README.md §raw-errsinkerrSink nil靜默吞掉錯誤。響應(yīng)頭路徑采用這種姿態(tài)——響應(yīng)頭上格式錯誤的 default/example 不會導(dǎo)致構(gòu)建失敗。DispatchHeaderLevel0與DispatchItemsLevel都接入了errSinknil。errSink ! nil以第一個ParseValueFromSchema錯誤調(diào)用它。返回true會在同一次 Walker 調(diào)用中短路后續(xù)的Raw回調(diào)閉包內(nèi)的stopped標志返回false則繼續(xù)。DispatchParamLevel0接入的 sink 會捕獲第一個錯誤并返回true見 dispatch_simple.go因此參數(shù)上格式錯誤的default:/example:會被作為硬失敗向上冒泡給調(diào)用方。集成測試套件中的TestMalformed_DefaultInt/TestMalformed_ExampleInt覆蓋了這一端到端行為該測試位于 codescan 倉庫的集成測試中本 vendored 目錄內(nèi)可在 handlers/README.md 找到對應(yīng)指引。從實現(xiàn)看Raw處理器handlers.go通過閉包stopped標志實現(xiàn)短路一旦 errSink 返回true后續(xù)所有屬性都會被跳過。此外當 full-Schema 專有的 raw 關(guān)鍵字如externalDocs:出現(xiàn)在 SimpleSchema 站點時若diag非 nil 會發(fā)出CodeUnsupportedInSimpleSchema警告并丟棄該關(guān)鍵字。collectionFormat 的寬松回退保留作者意圖CollectionFormatString優(yōu)先嘗試 Walker 提供的類型化字符串當該值為空語法中封閉詞匯的 string-enum 拒絕了源值時回退到strings.TrimSpace(pr.Value)把原始值原樣寫入詳見 handlers/README.md §collection-format-fallback。OAS v2 規(guī)范定義了封閉詞匯csv/ssv/tsv/pipes/multi但 codescan 語法在這個位置有意保持寬松像pipe這樣拼寫錯誤的pipes會原樣往返到參數(shù)或 items 對象上。這樣做的目的是把源碼作者的意圖保留給下游工具由下游直接對照規(guī)范文本暴露校驗錯誤。注意CollectionFormatString是 SimpleSchema 專屬full-Schema 的Validations適配器不暴露SetCollectionFormat因為collectionFormat:不是 full-Schema 關(guān)鍵字。實現(xiàn)位于 handlers.go其簽名依賴ifaces.OperationValidationBuilder參數(shù)與響應(yīng)頭兩個適配器都實現(xiàn)了該接口。SimpleSchema 關(guān)鍵字白名單與 required 例外keywords.go中的simpleSchemaAllowed枚舉了 OAS v2 SimpleSchema 站點in ! body的參數(shù)、響應(yīng)頭以及二者內(nèi)部的 items 鏈上合法的語法關(guān)鍵字名其權(quán)威來源是 OAS v2 Parameter Object 與 Header Object 的 allowed-keyword 表詳見 handlers/README.md §simple-schema-keywords。完整白名單keywords.go關(guān)鍵字對應(yīng)的 SettermaximumSetMaximumminimumSetMinimummultipleOfSetMultipleOfminLength/maxLengthSetMinLength/SetMaxLengthpatternSetPatternminItems/maxItemsSetMinItems/SetMaxItemsuniqueSetUniquecollectionFormatSetCollectionFormatdefault/example/enumSetDefault/SetExample/SetEnumrequiredparamRequiredBool參數(shù)層特例見下Vendor 擴展x-*不在白名單中——它們由classify.IsAllowedExtension按名稱前綴門控見 classify/extension.goIsAllowedExtension判斷鍵名是否以x-或X-開頭。required:之所以被列入 SimpleSchema 白名單是因為它在參數(shù)站點是合法的作為參數(shù)級布爾值但在響應(yīng)頭上不合法。由此產(chǎn)生兩個后果參數(shù) walker 通過paramRequiredBool把required:直接寫到param.Required見 dispatch_simple.go——值落在參數(shù)對象上而非 schema 上full-Schema walkerschemaBoolHandler在SimpleSchemaMode下靜默跳過required:因為它的 full-Schema 目標是enclosing.Required[name]——對象級 required 數(shù)組——與 SimpleSchema 形態(tài)不匹配見 dispatch_schema.go。IsSimpleSchemaKeyword對 full-Schema 專有關(guān)鍵字readOnly、discriminator、$ref、allOf等和未知名稱返回false。以 SimpleSchema 模式接線的消費者用這個謂詞門控寫入并在命中時發(fā)出CodeUnsupportedInSimpleSchema診斷。這一機制在Integer處理器handlers.go中體現(xiàn)為識別min/maxLength:與min/maxItems:其余整型關(guān)鍵字即 full-Schema 專屬的minProperties:/maxProperties:通過isFullSchemaOnly判定后發(fā)出警告并丟棄。vendor 擴展通過 AddExtension 落地ExtensionTarget是Walker.Extension消費者寫入 vendor 擴展所需的最小接口面詳見 handlers/README.md §extensions。它被所有嵌入了VendorExtensible的oaispec對象實現(xiàn)Schema、Parameter、Header、Response、Operation等通過從嵌入結(jié)構(gòu)提升的AddExtension方法完成寫入。Extension返回一個回調(diào)handlers.go該回調(diào)先用classify.IsAllowedExtension過濾非x-*名稱再把類型化的擴展值寫到目標對象上。關(guān)鍵細節(jié)用戶手寫的擴展不受SkipExtensions選項門控——該選項只抑制掃描器派生的x-go-*鍵不影響作者意圖。需要寫入成功后附加副作用例如 schema 構(gòu)建器的refOverrideCollector標記收集器的消費者應(yīng)該用自定義回調(diào)包裹該輔助函數(shù)而不是直接復(fù)用。這一點也在全包范圍內(nèi)通過Extension(param)、Extension(header)、Extension(ps)三個接線點體現(xiàn)分別在參數(shù)、響應(yīng)頭與 schema 分派器中。enum 覆蓋導(dǎo)致的陳舊 x-go-enum-desc 清理SchemaValidations.SetEnum先把解析出的 enum 寫到 schema 上隨后調(diào)用clearStaleEnumDesc在存在x-go-enum-desc擴展時將其剝離并同步把Description中匹配的后綴去掉詳見 handlers/README.md §stale-enum-desc。背景該擴展由類型級的swagger:enum TypeName通道設(shè)置攜帶每個枚舉值的文檔文本。當字段級enum:注解覆蓋了繼承值后原有的按值文檔文本所描述的值已不在字段級 enum 中——文檔變得陳舊必須丟棄以免產(chǎn)生誤導(dǎo)。實現(xiàn)位于 dispatch_schema.goclearStaleEnumDesc通過resolvers.GetEnumDesc讀取擴展刪除resolvers.ExtEnumDesc鍵并用strings.TrimSuffix依次去掉描述中的枚舉說明后綴與尾部換行。已記錄的待辦事項維護文檔列出了兩個有意推遲的后續(xù)項詳見 handlers/README.md §quirks-opencollectionFormat:的寬松接受?；赝说皆甲址怯幸獗Ａ羝磳戝e誤的行為。未來可考慮增加嚴格模式選項當值超出 OAS v2 封閉詞匯時發(fā)出診斷同時保留當前寬松默認值以維持兼容性。items 分派上的SchemaOptions.SimpleSchemaMode。該選項出于對稱性被DispatchSchemaItemsLevel接受但目前不改變 items 級行為。若未來 items 分派需要與 level-0 相同的門控值得重新審視。參考閱讀handlers 包維護文檔本文主體SimpleSchema 族分派實現(xiàn)full-Schema 族分派實現(xiàn)共享 Walker 回調(diào)與適配器實現(xiàn)SimpleSchema 關(guān)鍵字白名單關(guān)鍵字語法定義上下文、別名與形狀參數(shù)構(gòu)建器對分派器的調(diào)用點響應(yīng)構(gòu)建器對分派器的調(diào)用點vendor 擴展鍵名判定【免費下載鏈接】podmanPodman: A tool for managing OCI containers and pods.項目地址: https://gitcode.com/gh_mirrors/po/podman創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考