API style guide · Gitlab 中文文檔

# API style guide > 原文：[https://docs.gitlab.com/ee/development/api_styleguide.html](https://docs.gitlab.com/ee/development/api_styleguide.html) * [Instance variables](#instance-variables) * [Entities](#entities) * [Documentation](#documentation) * [Methods and parameters description](#methods-and-parameters-description) * [Declared parameters](#declared-parameters) * [Exclude parameters from parent namespaces](#exclude-parameters-from-parent-namespaces) * [When to use `declared(params)`](#when-to-use-declaredparams) * [Array types](#array-types) * [Automatic coercion of nil inputs](#automatic-coercion-of-nil-inputs) * [Using HTTP status helpers](#using-http-status-helpers) * [Using API path helpers in GitLab Rails codebase](#using-api-path-helpers-in-gitlab-rails-codebase) * [Custom Validators](#custom-validators) * [Using custom validators](#using-custom-validators) * [Adding a new custom validator](#adding-a-new-custom-validator) * [Internal API](#internal-api) * [Avoiding N+1 problems](#avoiding-n1-problems) * [Verifying with tests](#verifying-with-tests) * [Testing](#testing) # API style guide[](#api-style-guide "Permalink") 該樣式指南建議 API 開發的最佳做法. ## Instance variables[](#instance-variables "Permalink") 請不要使用實例變量，不需要它們（我們不需要像在 Rails 視圖中那樣訪問它們），可以使用局部變量. ## Entities[](#entities "Permalink") 始終使用[實體](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/entities)來呈現端點的有效負載. ## Documentation[](#documentation "Permalink") API 端點必須隨附[文檔](documentation/styleguide.html#api) ，除非[文檔](documentation/styleguide.html#api)在內部或在功能標志后面. 這些文檔應位于同一合并請求中，或者在嚴格必要的情況下，應與原始合并請求具有相同的里程碑. ## Methods and parameters description[](#methods-and-parameters-description "Permalink") 每種方法都必須使用[Grape DSL](https://github.com/ruby-grape/grape#describing-methods)進行描述（有關示例，請參見[https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/environments.rb](https://gitlab.com/gitlab-org/gitlab/blob/master/lib/api/environments.rb) ）： * `desc`的方法的總結. 您應該將其傳遞給其他細節，例如： * 添加端點時的 GitLab 版本. 如果它在功能標志后面，請提及： *該功能由：feature_flag_symbol 功能標志控制.* * 如果不贊成使用端點，那么，何時刪除它 * `params`方法參數. 這充當[參數的](https://github.com/ruby-grape/grape#parameter-validation-and-coercion)描述， [驗證和強制](https://github.com/ruby-grape/grape#parameter-validation-and-coercion) 一個很好的例子如下： ``` desc 'Get all broadcast messages' do detail 'This feature was introduced in GitLab 8.12.' success Entities::BroadcastMessage end params do optional :page, type: Integer, desc: 'Current page number' optional :per_page, type: Integer, desc: 'Number of messages per page' end get do messages = BroadcastMessage.all present paginate(messages), with: Entities::BroadcastMessage end ``` ## Declared parameters[](#declared-parameters "Permalink") > Grape 允許您僅訪問由`params`塊聲明的`params` . 它過濾掉已傳遞但不允許的參數. – [https://github.com/ruby-grape/grape#declared](https://github.com/ruby-grape/grape#declared) ### Exclude parameters from parent namespaces[](#exclude-parameters-from-parent-namespaces "Permalink") > 默認情況下， `declared(params)`包括在所有父名稱空間中定義的參數. – [https://github.com/ruby-grape/grape#include-parent-namespaces](https://github.com/ruby-grape/grape#include-parent-namespaces) 在大多數情況下，您將希望從父名稱空間中排除參數： ``` declared(params, include_parent_namespaces: false) ``` ### When to use `declared(params)`[](#when-to-use-declaredparams "Permalink") You should always use `declared(params)` when you pass the parameters hash as arguments to a method call. 例如： ``` # bad User.create(params) # imagine the user submitted `admin=1`... :) # good User.create(declared(params, include_parent_namespaces: false).to_h) ``` > **注意：** `Hashie::Mash` `declared(params)`返回一個`Hashie::Mash`對象，您必須在其上調用`.to_h` . 但是，當我們訪問單個元素時，可以直接使用`params[key]` . 例如： ``` # good Model.create(foo: params[:foo]) ``` ## Array types[](#array-types "Permalink") 在 Grape v1.3 +中，必須使用`coerce_with`塊定義數組類型，否則當從 API 請求傳遞字符串時，參數將無法驗證. 有關更多詳細信息，請參見[Grape 升級文檔](https://github.com/ruby-grape/grape/blob/master/UPGRADING.md#ensure-that-array-types-have-explicit-coercions) . ### Automatic coercion of nil inputs[](#automatic-coercion-of-nil-inputs "Permalink") 在 Grape v1.3.3 之前，具有`nil`值的 Array 參數將自動強制為空 Array. 但是，由于[v1.3.3 中的拉取請求，](https://github.com/ruby-grape/grape/pull/2040)情況不再如此. 例如，假設您定義一個具有可選參數的 PUT `/test`請求： ``` optional :user_ids, type: Array[Integer], coerce_with: ::API::Validations::Types::CommaSeparatedToIntegerArray.coerce, desc: 'The user ids for this rule' ``` 通常情況下，把一個請求`/test?user_ids`會導致葡萄傳遞`params`的`{ user_ids: nil }` . 這可能會導致端點期望為空數組且無法正確處理`nil`輸入的錯誤. 為了保留以前的行為，有一個輔助方法`coerce_nil_params_to_array!` 在所有 API 調用的`before`塊中使用的代碼： ``` before do coerce_nil_params_to_array! end ``` 進行此更改后，對 PUT `/test?user_ids`的請求將使 Grape 傳遞的`params`為`{ user_ids: [] }` . [Grape Tracker 中](https://github.com/ruby-grape/grape/issues/2068)存在[一個未解決的問題，](https://github.com/ruby-grape/grape/issues/2068)可以使此操作更容易. ## Using HTTP status helpers[](#using-http-status-helpers "Permalink") 對于非 200 HTTP 響應，請使用`lib/api/helpers.rb`提供的幫助`lib/api/helpers.rb`以確保行為正確（ `not_found!` ， `no_content!`等）. 這些將`throw` Grape 并中止端點的執行. 對于`DELETE`請求，通常還應該`destroy_conditionally!`地使用`destroy_conditionally!` 默認情況下，helper 會在成功時返回`204 No Content`響應，或者在給定的`If-Unmodified-Since`標頭超出范圍時返回`412 Precondition Failed` . 該助手在傳遞的資源上調用`#destroy` ，但是您也可以通過傳遞一個塊來實現自定義刪除方法. ## Using API path helpers in GitLab Rails codebase[](#using-api-path-helpers-in-gitlab-rails-codebase "Permalink") 因為我們支持[在相對 URL 下安裝 GitLab](../install/relative_url.html) ，所以在使用 Grape 生成的 API 路徑幫助程序時必須考慮到這一點. 任何此類 API 路徑幫助程序用法都必須包裝在`expose_path`幫助程序調用中. 例如： ``` - endpoint = expose_path(api_v4_projects_issues_related_merge_requests_path(id: @project.id, issue_iid: @issue.iid)) ``` ## Custom Validators[](#custom-validators "Permalink") 為了驗證 API 請求中的某些參數，我們先驗證它們，然后再進一步發送它們（例如 Gitaly）. 以下是[自定義驗證器](https://GitLab.com/gitlab-org/gitlab/-/tree/master/lib/api/validations/validators) ，到目前為止，我們已經添加了它們以及如何使用它們. 我們還編寫了有關如何添加新的自定義驗證器的指南. ### Using custom validators[](#using-custom-validators "Permalink") * `FilePath`: GitLab 支持我們需要遍歷文件路徑的各種功能. [`FilePath`驗證器](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators/file_path.rb)針對不同情況驗證參數值. 主要是，它使用`File::Separator`檢查路徑是否是相對路徑，是否包含`../../`相對遍歷，以及路徑是否是絕對路徑，例如`/etc/passwd/` . * `Git SHA`: [`Git SHA`驗證器](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators/git_sha.rb)檢查 Git SHA 參數是否為有效的 SHA. 它通過使用[`commit.rb`](https://gitlab.com/gitlab-org/gitlab/-/commit/b9857d8b662a2dbbf54f46ecdcecb44702affe55#d1c10892daedb4d4dd3d4b12b6d071091eea83df_30_30)文件中提到的正則表達式進行檢查. * `Absence`: [`Absence`驗證器](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators/absence.rb)檢查給定參數哈希中是否缺少特定參數. * `IntegerNoneAny`: [`IntegerNoneAny`驗證器](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators/integer_none_any.rb)檢查給定參數的值是`Integer` ， `None`還是`Any` . 它僅允許上述任何一個值在請求中前進. * `ArrayNoneAny`: [`ArrayNoneAny`驗證器](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators/array_none_any.rb)檢查給定參數的值是`Array` ， `None`還是`Any` . 它僅允許上述任何一個值在請求中前進. ### Adding a new custom validator[](#adding-a-new-custom-validator "Permalink") 自定義驗證器是在將參數發送到平臺進行進一步處理之前對其進行驗證的好方法. 如果我們在一開始就識別出無效的參數，它將在服務器和平臺之間來回保存一些時間. 如果您需要添加自定義驗證器，它將被添加到[`validators`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/lib/api/validations/validators)目錄中自己的文件中. 由于我們使用[Grape](https://github.com/ruby-grape/grape)添加 API，因此我們繼承了`Grape::Validations::Base`類中的`Grape::Validations::Base`類. 現在，您要做的就是定義`validate_param!` 該方法具有兩個參數： `params`哈希和要驗證的`param`名稱. 該方法的主體進行了驗證參數值的艱苦工作，并將適當的錯誤消息返回給調用方方法. 最后，我們使用以下行注冊驗證器： ``` Grape::Validations.register_validator(<validator name as symbol>, ::API::Helpers::CustomValidators::<YourCustomValidatorClassName>) ``` 添加驗證器后，請確保將其`rspec`添加到其在[`validators`](https://gitlab.com/gitlab-org/gitlab/-/blob/master/spec/lib/api/validations/validators)目錄中的自己的文件中. ## Internal API[](#internal-api "Permalink") [內部 API](./internal_api.html)已記錄供內部使用. 請保持最新狀態，以便我們了解不同組件正在使用哪些端點. ## Avoiding N+1 problems[](#avoiding-n1-problems "Permalink") 為了避免在 API 端點中返回記錄集合時常見的 N + 1 問題，我們應該使用預先加載. 在 API 中執行此操作的標準方法是讓模型實現一個名為`with_api_entity_associations`的范圍，該范圍將預加載 API 中返回的關聯和數據. 在[`Issue`模型中](https://gitlab.com/gitlab-org/gitlab/blob/2fedc47b97837ea08c3016cf2fb773a0300a4a25/app/models/issue.rb#L62)可以看到此范圍的示例. 在同一個模型的 API 中有多個實體的情況下（例如`UserBasic` ， `User`和`UserPublic` ），您應謹慎使用此范圍. 可能是您針對最基本的實體進行了優化，并在該范圍上建立了連續的實體. 當在 Todos API 中返回時， `with_api_entity_associations`范圍還將[自動](https://gitlab.com/gitlab-org/gitlab/blob/19f74903240e209736c7668132e6a5a735954e7c/app/models/todo.rb#L34)為`Todo` *目標* [預先加載數據](https://gitlab.com/gitlab-org/gitlab/blob/19f74903240e209736c7668132e6a5a735954e7c/app/models/todo.rb#L34) . 有關預加載的更多上下文和討論，請參閱[此合并請求](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25711) ， [該合并請求](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/25711)引入了作用域. ### Verifying with tests[](#verifying-with-tests "Permalink") 當 API 端點返回集合時，無論現在還是將來，始終添加一個測試以驗證 API 端點沒有 N + 1 問題. 我們可以使用[`ActiveRecord::QueryRecorder`](query_recorder.html)做到這一點. Example: ``` def make_api_request get api('/foo', personal_access_token: pat) end it 'avoids N+1 queries', :request_store do # Firstly, record how many PostgreSQL queries the endpoint will make # when it returns a single record create_record control = ActiveRecord::QueryRecorder.new { make_api_request } # Now create a second record and ensure that the API does not execute # any more queries than before create_record expect { make_api_request }.not_to exceed_query_limit(control) end ``` ## Testing[](#testing "Permalink") 在編寫新的 API 端點的測試，可以考慮使用模式[夾具](./testing_guide/best_practices.html#fixtures)位于`/spec/fixtures/api/schemas` . 您可以`expect`響應匹配給定的架構： ``` expect(response).to match_response_schema('merge_requests') ``` 另請參閱在測試中[驗證 N + 1 性能](#verifying-with-tests) .