diff options
author | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-20 16:18:24 +0300 |
---|---|---|
committer | GitLab Bot <gitlab-bot@gitlab.com> | 2021-09-20 16:18:24 +0300 |
commit | 0653e08efd039a5905f3fa4f6e9cef9f5d2f799c (patch) | |
tree | 4dcc884cf6d81db44adae4aa99f8ec1233a41f55 /doc/development/fe_guide/graphql.md | |
parent | 744144d28e3e7fddc117924fef88de5d9674fe4c (diff) |
Add latest changes from gitlab-org/gitlab@14-3-stable-eev14.3.0-rc42
Diffstat (limited to 'doc/development/fe_guide/graphql.md')
-rw-r--r-- | doc/development/fe_guide/graphql.md | 44 |
1 files changed, 37 insertions, 7 deletions
diff --git a/doc/development/fe_guide/graphql.md b/doc/development/fe_guide/graphql.md index 3b49601f027..0229aa0123a 100644 --- a/doc/development/fe_guide/graphql.md +++ b/doc/development/fe_guide/graphql.md @@ -421,14 +421,16 @@ is still validated. Again, make sure that those overrides are as short-lived as possible by tracking their removal in the appropriate issue. -#### Feature flags in queries +#### Feature-flagged queries -Sometimes it may be helpful to have an entity in the GraphQL query behind a feature flag. -One example is working on a feature where the backend has already been merged but the frontend -has not. In this case, you may consider putting the GraphQL entity behind a feature flag to allow smaller -merge requests to be created and merged. +In cases where the backend is complete and the frontend is being implemented behind a feature flag, +a couple options are available to leverage the feature flag in the GraphQL queries. -To do this we can use the `@include` directive to exclude an entity if the `if` statement passes. +##### The `@include` directive + +The `@include` (or its opposite, `@skip`) can be used to control whether an entity should be +included in the query. If the `@include` directive evaluates to `false`, the entity's resolver is +not hit and the entity is excluded from the response. For example: ```graphql query getAuthorData($authorNameEnabled: Boolean = false) { @@ -456,6 +458,34 @@ export default { }; ``` +Note that, even if the directive evaluates to `false`, the guarded entity is sent to the backend and +matched against the GraphQL schema. So this approach requires that the feature-flagged entity +exists in the schema, even if the feature flag is disabled. When the feature flag is turned off, it +is recommended that the resolver returns `null` at the very least. + +##### Different versions of a query + +There's another approach that involves duplicating the standard query, and it should be avoided. The copy includes the new entities +while the original remains unchanged. It is up to the production code to trigger the right query +based on the feature flag's status. For example: + +```javascript +export default { + apollo: { + user: { + query() { + return this.glFeatures.authorNameEnabled ? NEW_QUERY : ORIGINAL_QUERY, + } + } + }, +}; +``` + +This approach is not recommended as it results in bigger merge requests and requires maintaining +two similar queries for as long as the feature flag exists. This can be used in cases where the new +GraphQL entities are not yet part of the schema, or if they are feature-flagged at the schema level +(`new_entity: :feature_flag`). + ### Manually triggering queries Queries on a component's `apollo` property are made automatically when the component is created. @@ -1310,7 +1340,7 @@ describe('when query times out', () => { expect(getAlert().exists()).toBe(false); expect(getGraph().exists()).toBe(true); - /* fails again, alert retuns but data persists */ + /* fails again, alert returns but data persists */ await advanceApolloTimers(); expect(getAlert().exists()).toBe(true); expect(getGraph().exists()).toBe(true); |