├── .gitignore ├── LICENSE ├── README.md ├── manuscript ├── Book.txt ├── Sample.txt ├── chapter-0.md ├── chapter-1.md ├── chapter-2.md ├── chapter-3.md ├── chapter-4.md ├── chapter-5.md ├── chapter-6.md └── images │ ├── addpin-page.png │ ├── api.png │ ├── business-logic.png │ ├── client-server.png │ ├── client.png │ ├── current-file-structure.png │ ├── database.png │ ├── final-file-structure.png │ ├── graphql-playground.png │ ├── graphql-schema.png │ ├── http.png │ ├── login-page.png │ ├── pinlist-page.png │ ├── profile-page.png │ ├── schema.png │ ├── server-layers.png │ ├── server.png │ ├── subscriptions.png │ ├── title_page.png │ ├── types-resolvers.png │ └── verify-page.png ├── package.json └── styles ├── highlight.min.css └── styles.css /.gitignore: -------------------------------------------------------------------------------- 1 | WHITEBOARD.md 2 | .vscode 3 | scripts/hello-graphql/hello-graphql.sh 4 | *-error.log 5 | node_modules 6 | **/.DS_Store -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | Attribution-NonCommercial-ShareAlike 4.0 International 2 | 3 | ======================================================================= 4 | 5 | Creative Commons Corporation ("Creative Commons") is not a law firm and 6 | does not provide legal services or legal advice. Distribution of 7 | Creative Commons public licenses does not create a lawyer-client or 8 | other relationship. Creative Commons makes its licenses and related 9 | information available on an "as-is" basis. Creative Commons gives no 10 | warranties regarding its licenses, any material licensed under their 11 | terms and conditions, or any related information. Creative Commons 12 | disclaims all liability for damages resulting from their use to the 13 | fullest extent possible. 14 | 15 | Using Creative Commons Public Licenses 16 | 17 | Creative Commons public licenses provide a standard set of terms and 18 | conditions that creators and other rights holders may use to share 19 | original works of authorship and other material subject to copyright 20 | and certain other rights specified in the public license below. The 21 | following considerations are for informational purposes only, are not 22 | exhaustive, and do not form part of our licenses. 23 | 24 | Considerations for licensors: Our public licenses are 25 | intended for use by those authorized to give the public 26 | permission to use material in ways otherwise restricted by 27 | copyright and certain other rights. Our licenses are 28 | irrevocable. Licensors should read and understand the terms 29 | and conditions of the license they choose before applying it. 30 | Licensors should also secure all rights necessary before 31 | applying our licenses so that the public can reuse the 32 | material as expected. Licensors should clearly mark any 33 | material not subject to the license. This includes other CC- 34 | licensed material, or material used under an exception or 35 | limitation to copyright. More considerations for licensors: 36 | wiki.creativecommons.org/Considerations_for_licensors 37 | 38 | Considerations for the public: By using one of our public 39 | licenses, a licensor grants the public permission to use the 40 | licensed material under specified terms and conditions. If 41 | the licensor's permission is not necessary for any reason--for 42 | example, because of any applicable exception or limitation to 43 | copyright--then that use is not regulated by the license. Our 44 | licenses grant only permissions under copyright and certain 45 | other rights that a licensor has authority to grant. Use of 46 | the licensed material may still be restricted for other 47 | reasons, including because others have copyright or other 48 | rights in the material. A licensor may make special requests, 49 | such as asking that all changes be marked or described. 50 | Although not required by our licenses, you are encouraged to 51 | respect those requests where reasonable. More considerations 52 | for the public: 53 | wiki.creativecommons.org/Considerations_for_licensees 54 | 55 | ======================================================================= 56 | 57 | Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International 58 | Public License 59 | 60 | By exercising the Licensed Rights (defined below), You accept and agree 61 | to be bound by the terms and conditions of this Creative Commons 62 | Attribution-NonCommercial-ShareAlike 4.0 International Public License 63 | ("Public License"). To the extent this Public License may be 64 | interpreted as a contract, You are granted the Licensed Rights in 65 | consideration of Your acceptance of these terms and conditions, and the 66 | Licensor grants You such rights in consideration of benefits the 67 | Licensor receives from making the Licensed Material available under 68 | these terms and conditions. 69 | 70 | 71 | Section 1 -- Definitions. 72 | 73 | a. Adapted Material means material subject to Copyright and Similar 74 | Rights that is derived from or based upon the Licensed Material 75 | and in which the Licensed Material is translated, altered, 76 | arranged, transformed, or otherwise modified in a manner requiring 77 | permission under the Copyright and Similar Rights held by the 78 | Licensor. For purposes of this Public License, where the Licensed 79 | Material is a musical work, performance, or sound recording, 80 | Adapted Material is always produced where the Licensed Material is 81 | synched in timed relation with a moving image. 82 | 83 | b. Adapter's License means the license You apply to Your Copyright 84 | and Similar Rights in Your contributions to Adapted Material in 85 | accordance with the terms and conditions of this Public License. 86 | 87 | c. BY-NC-SA Compatible License means a license listed at 88 | creativecommons.org/compatiblelicenses, approved by Creative 89 | Commons as essentially the equivalent of this Public License. 90 | 91 | d. Copyright and Similar Rights means copyright and/or similar rights 92 | closely related to copyright including, without limitation, 93 | performance, broadcast, sound recording, and Sui Generis Database 94 | Rights, without regard to how the rights are labeled or 95 | categorized. For purposes of this Public License, the rights 96 | specified in Section 2(b)(1)-(2) are not Copyright and Similar 97 | Rights. 98 | 99 | e. Effective Technological Measures means those measures that, in the 100 | absence of proper authority, may not be circumvented under laws 101 | fulfilling obligations under Article 11 of the WIPO Copyright 102 | Treaty adopted on December 20, 1996, and/or similar international 103 | agreements. 104 | 105 | f. Exceptions and Limitations means fair use, fair dealing, and/or 106 | any other exception or limitation to Copyright and Similar Rights 107 | that applies to Your use of the Licensed Material. 108 | 109 | g. License Elements means the license attributes listed in the name 110 | of a Creative Commons Public License. The License Elements of this 111 | Public License are Attribution, NonCommercial, and ShareAlike. 112 | 113 | h. Licensed Material means the artistic or literary work, database, 114 | or other material to which the Licensor applied this Public 115 | License. 116 | 117 | i. Licensed Rights means the rights granted to You subject to the 118 | terms and conditions of this Public License, which are limited to 119 | all Copyright and Similar Rights that apply to Your use of the 120 | Licensed Material and that the Licensor has authority to license. 121 | 122 | j. Licensor means the individual(s) or entity(ies) granting rights 123 | under this Public License. 124 | 125 | k. NonCommercial means not primarily intended for or directed towards 126 | commercial advantage or monetary compensation. For purposes of 127 | this Public License, the exchange of the Licensed Material for 128 | other material subject to Copyright and Similar Rights by digital 129 | file-sharing or similar means is NonCommercial provided there is 130 | no payment of monetary compensation in connection with the 131 | exchange. 132 | 133 | l. Share means to provide material to the public by any means or 134 | process that requires permission under the Licensed Rights, such 135 | as reproduction, public display, public performance, distribution, 136 | dissemination, communication, or importation, and to make material 137 | available to the public including in ways that members of the 138 | public may access the material from a place and at a time 139 | individually chosen by them. 140 | 141 | m. Sui Generis Database Rights means rights other than copyright 142 | resulting from Directive 96/9/EC of the European Parliament and of 143 | the Council of 11 March 1996 on the legal protection of databases, 144 | as amended and/or succeeded, as well as other essentially 145 | equivalent rights anywhere in the world. 146 | 147 | n. You means the individual or entity exercising the Licensed Rights 148 | under this Public License. Your has a corresponding meaning. 149 | 150 | 151 | Section 2 -- Scope. 152 | 153 | a. License grant. 154 | 155 | 1. Subject to the terms and conditions of this Public License, 156 | the Licensor hereby grants You a worldwide, royalty-free, 157 | non-sublicensable, non-exclusive, irrevocable license to 158 | exercise the Licensed Rights in the Licensed Material to: 159 | 160 | a. reproduce and Share the Licensed Material, in whole or 161 | in part, for NonCommercial purposes only; and 162 | 163 | b. produce, reproduce, and Share Adapted Material for 164 | NonCommercial purposes only. 165 | 166 | 2. Exceptions and Limitations. For the avoidance of doubt, where 167 | Exceptions and Limitations apply to Your use, this Public 168 | License does not apply, and You do not need to comply with 169 | its terms and conditions. 170 | 171 | 3. Term. The term of this Public License is specified in Section 172 | 6(a). 173 | 174 | 4. Media and formats; technical modifications allowed. The 175 | Licensor authorizes You to exercise the Licensed Rights in 176 | all media and formats whether now known or hereafter created, 177 | and to make technical modifications necessary to do so. The 178 | Licensor waives and/or agrees not to assert any right or 179 | authority to forbid You from making technical modifications 180 | necessary to exercise the Licensed Rights, including 181 | technical modifications necessary to circumvent Effective 182 | Technological Measures. For purposes of this Public License, 183 | simply making modifications authorized by this Section 2(a) 184 | (4) never produces Adapted Material. 185 | 186 | 5. Downstream recipients. 187 | 188 | a. Offer from the Licensor -- Licensed Material. Every 189 | recipient of the Licensed Material automatically 190 | receives an offer from the Licensor to exercise the 191 | Licensed Rights under the terms and conditions of this 192 | Public License. 193 | 194 | b. Additional offer from the Licensor -- Adapted Material. 195 | Every recipient of Adapted Material from You 196 | automatically receives an offer from the Licensor to 197 | exercise the Licensed Rights in the Adapted Material 198 | under the conditions of the Adapter's License You apply. 199 | 200 | c. No downstream restrictions. You may not offer or impose 201 | any additional or different terms or conditions on, or 202 | apply any Effective Technological Measures to, the 203 | Licensed Material if doing so restricts exercise of the 204 | Licensed Rights by any recipient of the Licensed 205 | Material. 206 | 207 | 6. No endorsement. Nothing in this Public License constitutes or 208 | may be construed as permission to assert or imply that You 209 | are, or that Your use of the Licensed Material is, connected 210 | with, or sponsored, endorsed, or granted official status by, 211 | the Licensor or others designated to receive attribution as 212 | provided in Section 3(a)(1)(A)(i). 213 | 214 | b. Other rights. 215 | 216 | 1. Moral rights, such as the right of integrity, are not 217 | licensed under this Public License, nor are publicity, 218 | privacy, and/or other similar personality rights; however, to 219 | the extent possible, the Licensor waives and/or agrees not to 220 | assert any such rights held by the Licensor to the limited 221 | extent necessary to allow You to exercise the Licensed 222 | Rights, but not otherwise. 223 | 224 | 2. Patent and trademark rights are not licensed under this 225 | Public License. 226 | 227 | 3. To the extent possible, the Licensor waives any right to 228 | collect royalties from You for the exercise of the Licensed 229 | Rights, whether directly or through a collecting society 230 | under any voluntary or waivable statutory or compulsory 231 | licensing scheme. In all other cases the Licensor expressly 232 | reserves any right to collect such royalties, including when 233 | the Licensed Material is used other than for NonCommercial 234 | purposes. 235 | 236 | 237 | Section 3 -- License Conditions. 238 | 239 | Your exercise of the Licensed Rights is expressly made subject to the 240 | following conditions. 241 | 242 | a. Attribution. 243 | 244 | 1. If You Share the Licensed Material (including in modified 245 | form), You must: 246 | 247 | a. retain the following if it is supplied by the Licensor 248 | with the Licensed Material: 249 | 250 | i. identification of the creator(s) of the Licensed 251 | Material and any others designated to receive 252 | attribution, in any reasonable manner requested by 253 | the Licensor (including by pseudonym if 254 | designated); 255 | 256 | ii. a copyright notice; 257 | 258 | iii. a notice that refers to this Public License; 259 | 260 | iv. a notice that refers to the disclaimer of 261 | warranties; 262 | 263 | v. a URI or hyperlink to the Licensed Material to the 264 | extent reasonably practicable; 265 | 266 | b. indicate if You modified the Licensed Material and 267 | retain an indication of any previous modifications; and 268 | 269 | c. indicate the Licensed Material is licensed under this 270 | Public License, and include the text of, or the URI or 271 | hyperlink to, this Public License. 272 | 273 | 2. You may satisfy the conditions in Section 3(a)(1) in any 274 | reasonable manner based on the medium, means, and context in 275 | which You Share the Licensed Material. For example, it may be 276 | reasonable to satisfy the conditions by providing a URI or 277 | hyperlink to a resource that includes the required 278 | information. 279 | 3. If requested by the Licensor, You must remove any of the 280 | information required by Section 3(a)(1)(A) to the extent 281 | reasonably practicable. 282 | 283 | b. ShareAlike. 284 | 285 | In addition to the conditions in Section 3(a), if You Share 286 | Adapted Material You produce, the following conditions also apply. 287 | 288 | 1. The Adapter's License You apply must be a Creative Commons 289 | license with the same License Elements, this version or 290 | later, or a BY-NC-SA Compatible License. 291 | 292 | 2. You must include the text of, or the URI or hyperlink to, the 293 | Adapter's License You apply. You may satisfy this condition 294 | in any reasonable manner based on the medium, means, and 295 | context in which You Share Adapted Material. 296 | 297 | 3. You may not offer or impose any additional or different terms 298 | or conditions on, or apply any Effective Technological 299 | Measures to, Adapted Material that restrict exercise of the 300 | rights granted under the Adapter's License You apply. 301 | 302 | 303 | Section 4 -- Sui Generis Database Rights. 304 | 305 | Where the Licensed Rights include Sui Generis Database Rights that 306 | apply to Your use of the Licensed Material: 307 | 308 | a. for the avoidance of doubt, Section 2(a)(1) grants You the right 309 | to extract, reuse, reproduce, and Share all or a substantial 310 | portion of the contents of the database for NonCommercial purposes 311 | only; 312 | 313 | b. if You include all or a substantial portion of the database 314 | contents in a database in which You have Sui Generis Database 315 | Rights, then the database in which You have Sui Generis Database 316 | Rights (but not its individual contents) is Adapted Material, 317 | including for purposes of Section 3(b); and 318 | 319 | c. You must comply with the conditions in Section 3(a) if You Share 320 | all or a substantial portion of the contents of the database. 321 | 322 | For the avoidance of doubt, this Section 4 supplements and does not 323 | replace Your obligations under this Public License where the Licensed 324 | Rights include other Copyright and Similar Rights. 325 | 326 | 327 | Section 5 -- Disclaimer of Warranties and Limitation of Liability. 328 | 329 | a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE 330 | EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS 331 | AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF 332 | ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, 333 | IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, 334 | WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR 335 | PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, 336 | ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT 337 | KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT 338 | ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. 339 | 340 | b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE 341 | TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, 342 | NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, 343 | INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, 344 | COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR 345 | USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN 346 | ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR 347 | DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR 348 | IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. 349 | 350 | c. The disclaimer of warranties and limitation of liability provided 351 | above shall be interpreted in a manner that, to the extent 352 | possible, most closely approximates an absolute disclaimer and 353 | waiver of all liability. 354 | 355 | 356 | Section 6 -- Term and Termination. 357 | 358 | a. This Public License applies for the term of the Copyright and 359 | Similar Rights licensed here. However, if You fail to comply with 360 | this Public License, then Your rights under this Public License 361 | terminate automatically. 362 | 363 | b. Where Your right to use the Licensed Material has terminated under 364 | Section 6(a), it reinstates: 365 | 366 | 1. automatically as of the date the violation is cured, provided 367 | it is cured within 30 days of Your discovery of the 368 | violation; or 369 | 370 | 2. upon express reinstatement by the Licensor. 371 | 372 | For the avoidance of doubt, this Section 6(b) does not affect any 373 | right the Licensor may have to seek remedies for Your violations 374 | of this Public License. 375 | 376 | c. For the avoidance of doubt, the Licensor may also offer the 377 | Licensed Material under separate terms or conditions or stop 378 | distributing the Licensed Material at any time; however, doing so 379 | will not terminate this Public License. 380 | 381 | d. Sections 1, 5, 6, 7, and 8 survive termination of this Public 382 | License. 383 | 384 | 385 | Section 7 -- Other Terms and Conditions. 386 | 387 | a. The Licensor shall not be bound by any additional or different 388 | terms or conditions communicated by You unless expressly agreed. 389 | 390 | b. Any arrangements, understandings, or agreements regarding the 391 | Licensed Material not stated herein are separate from and 392 | independent of the terms and conditions of this Public License. 393 | 394 | 395 | Section 8 -- Interpretation. 396 | 397 | a. For the avoidance of doubt, this Public License does not, and 398 | shall not be interpreted to, reduce, limit, restrict, or impose 399 | conditions on any use of the Licensed Material that could lawfully 400 | be made without permission under this Public License. 401 | 402 | b. To the extent possible, if any provision of this Public License is 403 | deemed unenforceable, it shall be automatically reformed to the 404 | minimum extent necessary to make it enforceable. If the provision 405 | cannot be reformed, it shall be severed from this Public License 406 | without affecting the enforceability of the remaining terms and 407 | conditions. 408 | 409 | c. No term or condition of this Public License will be waived and no 410 | failure to comply consented to unless expressly agreed to by the 411 | Licensor. 412 | 413 | d. Nothing in this Public License constitutes or may be interpreted 414 | as a limitation upon, or waiver of, any privileges and immunities 415 | that apply to the Licensor or You, including from the legal 416 | processes of any jurisdiction or authority. 417 | 418 | ======================================================================= 419 | 420 | Creative Commons is not a party to its public 421 | licenses. Notwithstanding, Creative Commons may elect to apply one of 422 | its public licenses to material it publishes and in those instances 423 | will be considered the “Licensor.” The text of the Creative Commons 424 | public licenses is dedicated to the public domain under the CC0 Public 425 | Domain Dedication. Except for the limited purpose of indicating that 426 | material is shared under a Creative Commons public license or as 427 | otherwise permitted by the Creative Commons policies published at 428 | creativecommons.org/policies, Creative Commons does not authorize the 429 | use of the trademark "Creative Commons" or any other trademark or logo 430 | of Creative Commons without its prior written consent including, 431 | without limitation, in connection with any unauthorized modifications 432 | to any of its public licenses or any other arrangements, 433 | understandings, or agreements concerning use of licensed material. For 434 | the avoidance of doubt, this paragraph does not form part of the 435 | public licenses. 436 | 437 | Creative Commons may be contacted at creativecommons.org. 438 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Полностековый GraphQL (русский перевод) 2 | 3 | Книга о фулстек-разработке GraphQL с помощью React и Node. 4 | 5 | https://graphql.college/fullstack-graphql. 6 | 7 | 8 | Cover 9 | 10 | 11 | ## Структура 12 | 13 | Каждая глава написана в файлах формата Markdown в каталоге `manuscript`. 14 | 15 | Каждое изображение книги находится в `manuscript/images`. 16 | 17 | Порядок глав определяется файлом `Book.txt`. 18 | 19 | `Sample.txt` — содержимое для образца главы книги. 20 | 21 | ## Участие в проекте 22 | 23 | Все типы участия приветствуются! Вот небольшой указатель, как можно внести свой вклад. 24 | 25 | ### Баги/опечатки 26 | 27 | Если вы увидели баг или опечатку, пожалуйста, откройте ишью в этом репозитории на GitHub. 28 | 29 | ### Исправления 30 | 31 | Для исправления примера, пожалуйста, пересоздайте код примера в Glitch и создайте пулреквест, ссылающиеся на исправленный URL-адрес в Glitch. 32 | 33 | ### Новые главы 34 | 35 | Пожалуйста, создайте ишью для предложения новых глав. Предложения новых глав всегда приветствуются! Но, пожалуйста, не создавайте пулреквест с новой главой до её обсуждения, поскольку она может быть не принята. Время — золото, используйте его с умом! 36 | 37 | ### Вопросы 38 | 39 | Если у вас есть какие-либо вопросы относительно книги или GraphQL в целом, пожалуйста, создайте переписку в https://spectrum.chat/graphql вместо ишью на GitHub. 40 | 41 | ## Лицензия 42 | 43 | ![CC](https://creativecommons.org/images/deed/cc_blue_x2.png) 44 | ![Attribution](https://creativecommons.org/images/deed/attribution_icon_blue_x2.png) 45 | ![NC](https://creativecommons.org/images/deed/nc_blue_x2.png) 46 | ![SA](https://creativecommons.org/images/deed/sa_blue_x2.png) 47 | 48 | Данная книга распространяется на условиях лицензии [Creative Commons Attribution Non Commercial Share Alike 4.0 International](https://creativecommons.org/licenses/by-nc-sa/4.0/). 49 | -------------------------------------------------------------------------------- /manuscript/Book.txt: -------------------------------------------------------------------------------- 1 | chapter-0.md 2 | chapter-1.md 3 | chapter-2.md 4 | chapter-3.md 5 | chapter-4.md 6 | chapter-5.md 7 | chapter-6.md -------------------------------------------------------------------------------- /manuscript/Sample.txt: -------------------------------------------------------------------------------- 1 | chapter-0.md 2 | chapter-1.md -------------------------------------------------------------------------------- /manuscript/chapter-0.md: -------------------------------------------------------------------------------- 1 | # Предисловие 2 | 3 | GraphQL — революционное решение в клиент-серверном взаимодействии. Эта технология позволяет лучше документировать API, облегчает управление данными в HTTP-клиентах и оптимизирует использование сети. 4 | 5 | Одно из основных преимуществ GraphQL — улучшение контакта между API и его пользователями. Кроме этого, технология позволяет улучшить работу в команде разработчиков, предоставляя им информацию о методах API. Он также обеспечивает лучшее взаимодействие со сторонними пользователями API, поскольку сервисам GraphQL не требуется конфигурация для API-документации. 6 | 7 | Учитывая вышесказанное, GraphQL расширяет возможности клиентов, давая им полный контроль над получением данных. GraphQL позволяет клиентам запрашивать только те данные, которые им нужны, — ни больше ни меньше. Технология также предоставляет возможность запрашивать и вложенные данные, используя один запрос и избегая нескольких простых запросов, как это принято в RESTful API. REST порождает тенденцию к сложности использования API для клиентов. 8 | 9 | Как следствие, GraphQL оптимизирует использование сети за счёт уменьшения отправляемых данных и количества HTTP-запросов. Данное преимущество особенно заметно на мобильных клиентах, где интернет-трафик играет важную роль. 10 | 11 | ## Итак, что же такое GraphQL? 12 | 13 | GraphQL — типизированный предметно-ориентированный язык для проектирования и запросов данных. 14 | 15 | Предметно-ориентированный язык или DSL — это язык, созданный для единственной предметной области приложения; он противоположен языкам общего назначения, таким как JavaScript, Ruby, Python или C, которые применяются для решения самых разных задач. В настоящее время существует множество популярных DSL: CSS — это DSL для оформления (стилизации), а HTML — это DSL для разметки. И вот GraphQL — это DSL для данных. 16 | 17 | GraphQL — типизированный язык, а это значит, что он использует типы для определения ресурсов, добавляет типы в поля каждого ресурса. Он также использует типы для статической проверки ошибок. Как упоминалось, это типизированный язык, поэтому он является источником самых больших достоинств GraphQL, таких как автоматическая интроспекция API и документация. 18 | 19 | Предметная область GraphQL — это данные. Он может использоваться для разработки схемы, представляющей данные, а также для запроса определённых полей данных. 20 | 21 | Разработка серверов и клиентов API — основной вариант использования GraphQL. Бэкенд-разработчики могут использовать GraphQL для моделирования своих данных, в то время как фронтенд-разработчики могут использовать GraphQL для формулирования запросов на получения определённых частей данных. 22 | 23 | Даже несмотря на то, что сервисы обычно включают GraphQL через HTTP-уровень, тем не менее GraphQL не привязан строго к HTTP или какому-либо другому протоколу передачи данных. 24 | 25 | В конце концов, GraphQL — это спецификация. Это означает, как он должен работать, позволяя любому реализовать его на любом языке программирования. Существует официальная реализация на JavaScript под названием `graphql-js`, но есть также множество других реализаций на разных языках программирования, таких как Ruby, Elixir и т.д. 26 | 27 | ## Организация книги 28 | 29 | В этой книге вы узнаете, как с нуля разработать готовое клиент-серверное приложение, использующее GraphQL. Вы научитесь получать данные от клиента, проектировать эти данные на сервере, разрабатывать GraphQL-серверы на Node.js и, наконец, как создавать клиенты на React с использованием GraphQL. 30 | 31 | Первые две главы покажут, как получать данные с помощью GraphQL. В первой главе вы познакомитесь с тем, как создавать данные. Во второй главе изучите, как проектировать схемы. Вы узнаете эти чистые концепции GraphQL, не задумываясь про серверы или клиенты HTTP. GraphQL — это абстракция, позволяющая думать о данных, не беспокоясь о том, как они будут передаваться. Вы создадите схему, запросы и мутации с помощью JavaScript и нескольких библиотек GraphQL. 32 | 33 | Остальные главы будут посвящены созданию серверов и клиентов GraphQL. 34 | 35 | В третьей главе, API GraphQL, вы узнаете, как создавать HTTP-серверы GraphQL с использованием серверов Node.js и Apollo. Вы сделаете доступной GraphQL-схему через HTTP, подключитесь к базе данных, реализуете аутентификацию и авторизацию, а также узнаете, как лучше организовать файловую структуру. 36 | 37 | В четвёртой главе, Клиенты GraphQL, вы научитесь разрабатывать GraphQL-клиенты с помощью клиента React и Apollo. Вы узнаете, как запрашивать и создавать данные с использованием Apollo-компонентов `Query` и `Mutation`, а также как обрабатывать аутентификацию. 38 | 39 | В пятой главе вы освоите добавление функциональности, работающей в режиме реального времени к вашим приложениям GraphQL с помощью подписок. Подписки предоставляют API-интерфейсам GraphQL возможность передавать данные клиентам. 40 | 41 | Наконец, в шестой главе вы познакомитесь с тестированием API и GraphQL-клиентов. 42 | 43 | ## Пример приложения 44 | 45 | В ходе этой книги вы узнаете, как создать клон сервииса Pinterest под названием Pinapp с использованием GraphQL, Node.js, React и Apollo-клиента. 46 | 47 | Для Pinapp определены следующие требования: 48 | 49 | * Вход с помощью магических ссылок 50 | * Выход из приложения 51 | * Добавление пина (изображения со ссылкой на URL-адрес) 52 | * Возможность поиска пинов и пользователей 53 | * Просмотр списка пинов 54 | * Просмотр новых пинов без обновления браузера 55 | 56 | Вы создадите это приложение слоями. Начнёте со слоя данных, затем напишите бизнес-логику, после чего перейдёте к транспортному уровню HTTP, а затем соедините всё это с уровнем базы данных и, наконец, реализуете HTTP-клиент. 57 | 58 | ## Окружение для разработки 59 | 60 | Нет никаких требований к окружению, чтобы посмотреть вживую примеры из этой книги, кроме наличия браузера и подключения к интернету. На каждом шаге приложения есть работающая и доступна для клонирования онлайн-версия на glitch.com. Glitch — потрясающий сервис для создания приложений, созданное людьми, которые разработали Stack Overflow и Trello. 61 | -------------------------------------------------------------------------------- /manuscript/chapter-1.md: -------------------------------------------------------------------------------- 1 | # 1. Чтение и запись 2 | 3 | В этой главе вы узнаете, как использовать GraphQL с точки зрения разработчика. Объясняется, как использовать запросы[^queries_note] и мутации для чтения и записи данных сервера GraphQL. 4 | 5 | ![Запросы и мутации](images/graphql-schema.png) 6 | 7 | По мере изучения возможностей GraphQL, вы поймете, что это та технология, которая делает жизнь намного проще для фронтенд-разработчиков. GraphQL предоставляет полный контроль над данными, которые можно получить с сервера. 8 | 9 | Сделать жизнь проще для клиента — это одна из главных задач создателей GraphQL. Результат эволюции языка демонстрирует следующий доклад: [Client-Driven Development](https://youtu.be/vQkGO5q52uE). 10 | 11 | ## 1.1 Запросы и мутации 12 | 13 | В самом простом виде GraphQL предоставляет возможность запрашивать набор полей (fields). 14 | 15 | Сам язык GraphQL определяет, как именно взаимодействовать с сервером. Запросы, в эталонном их виде, служат для получения данных, в то время как мутации требуются для того, чтобы эти данные записывать. Запросы служат той же цели, что и GET-запросам в старом добром REST, а мутации аналогичны методам POST, PUT, PATCH и DELETE. 16 | 17 | В этой главе вы узнаете о следующих возможностях синтаксиса GraphQL: 18 | 19 | * Простой запрос 20 | * Запрос вложенных полей 21 | * Запрос нескольких полей 22 | * Наименование операции 23 | * Аргументы 24 | * Псевдонимы 25 | * Фрагменты 26 | * Переменные 27 | * Директивы 28 | * Переменные по умолчанию 29 | * Мутации 30 | * Встроенные фрагменты 31 | * Метаинформация 32 | 33 | Все концепции, о которых вы узнаете, имеют примеры, реализованные с помощью [`graphql-js`](https://github.com/graphql/graphql-js). GraphQL JS — эталонная реализация GraphQL, написанная на JavaScript. Сама библиотека предоставляет функцию `graphql, позволяющая передать запрос в схему GraphQL. 34 | 35 | Примеры в этой главе уже содержат базовую реализацию схемы GraphQL. Не волнуйтесь, если вы еще не понимаете, как всё это работает. В этой главе мы сосредоточимся на самих GraphQL-запросах, в то время как следующая будет посвящена созданию схемы. Обратите внимание, что приведённая схема содержит очень простую реализацию, поэтому не ожидайте большего, кроме случайных чисел или классический «Hello world» в качестве ответов сервера. Следующая глава научит вас правильно проектировать эту схему. 36 | 37 | Несмотря на то, что GraphQL предназначен для использования HTTP-клиентами и работает с HTTP-сервером, выполнение запросов с использованием JavaScript-консоли поможет понять основы языка без каких-либо накладных расходов, т.е. без настройки сервера и прочего. 38 | 39 | Му воспользуемся функцией `graphql`, которая экспортируется из `graphql-js`. В простейшем виде она принимает два аргумента и возвращает объект Promise. Первый аргумент — это объект схемы GraphQL. Второй аргумент — это строка, содержащая запрос GraphQL. Все примеры в этой главе расскажут вам, как написать этот запрос. Если же вы хотите узнать чуть больше, то всегда можно воспользоваться [документацией по API `graphql-js`](http://graphql.org/graphql-js/graphql/#graphql). 40 | 41 | ```js 42 | const { graphql } = require("graphql"); 43 | 44 | const schema = require("../schema"); 45 | 46 | const query = ``; 47 | 48 | graphql(schema, query).then(result => 49 | console.log(JSON.stringify(result, null, 1)) 50 | ); 51 | ``` 52 | 53 | Воспользуйтесь [копированием этого примера в сервис Glitch](https://glitch.com/edit/#!/remix/pinapp-queries-mutations), чтобы получить возможность сразу же запустить и посмотреть в действии код, показанный в этой главе. Это даст вам полную свободу над проектом. Вы можете модифицировать его по своему усмотрению, запускать скрипты с помощью консоли и даже экспортировать его в GitHub. 54 | 55 | После копирования этого проекта вы можете запустить любой из скриптов в папке `queries`. Далее откройте консоль, нажав «Logs», а затем «Console», и выполните `node query/1-query.js` для просмотра выходных данных первого скрипта. 56 | 57 | Теперь у вас есть все необходимое, чтобы начать изучение синтаксиса GraphQL. Давайте уже приступим к отправке основных запросов. 58 | 59 | You have everything you need to start learning GraphQL query syntax. Let's start by sending basic queries. 60 | 61 | Как мы уже говорили в начале этой главы, GraphQL предоставляет возможность запрашивать конкретные поля объектов. Запрос определяет, какие именно поля будет иметь ответ GraphQL в формате JSON[^chapter1-json]. Синтаксис языка запросов очень похож на формат объектов в JSON с перечислением ключей без их значений. Например, если вы хотите получить список пользователей, каждый из которых имеет поле электронной почты, вы можете написать следующий запрос: 62 | 63 | [^chapter1-json]: GraphQL не накладывает никаких ограничений на формат ответов сервера, однако JSON является самым популярным и довольно читаемым вариантом. 64 | 65 | ```graphql 66 | { 67 | users { 68 | email 69 | } 70 | } 71 | ``` 72 | 73 | Вы можете передать этот запрос вместе со схемой в функцию `graphql`. Помните, что именно второй аргумент, передаваемый в функцию `graphql`, является строкой запроса. Давайте посмотрим пример скрипта. 74 | 75 | `queries/1-query.js` 76 | 77 | ```js 78 | const { graphql } = require("graphql"); 79 | 80 | const schema = require("../schema"); 81 | 82 | const query = ` 83 | { 84 | users { 85 | email 86 | } 87 | } 88 | `; 89 | 90 | graphql(schema, query).then(result => 91 | console.log(JSON.stringify(result, null, 1)) 92 | ); 93 | ``` 94 | 95 | Запуск приведённого выше кода в консоли вернёт ответ с корневым ключом `"data"`, в котором есть все запрошенные в запросе поля. Внутри поля `"data"` вы увидите структуру, которая точно соответствует отправленному запросу: вы увидите ключ `"users"`, который в свою очередь содержит массив объектов с ключом `"email"`. 96 | 97 | ```bash 98 | $ node queries/1-query.js 99 | { 100 | "data": { 101 | "users": [ 102 | { 103 | "email": "Hello World" 104 | }, 105 | { 106 | "email": "Hello World" 107 | } 108 | ] 109 | } 110 | } 111 | ``` 112 | 113 | ## 1.3 Вложенные поля 114 | 115 | Используя GraphQL можно запросить вложенные поля. Одно из больших преимуществ GraphQL по сравнению с REST — это выборка вложенных ресурсов в одном запросе. Вы можете запросить ресурс, например пользователей, а также список вложенных ресурсов, например, пинов[^pins], в одном запросе. Чтобы сделать это с помощью REST, вам потребуется запрашивать пользователей и пины в отдельных HTTP-запросах. 116 | 117 | [^pins]: Под _пином_, как правило, подразумевается изображение, у которого необязательно может быть название, описание, ссылка (источник изображения). Название пришло из сервиса Pinterest, в котором пользователь может создавать пины. 118 | 119 | Обратите внимание, что только поля с типом `Object` могут иметь вложенные поля. Вы не можете запрашивать вложенные поля из других типов, таких как `String`, `Int` и др. 120 | 121 | ```js 122 | const { graphql } = require("graphql"); 123 | 124 | const schema = require("../schema"); 125 | 126 | const query = ` 127 | { 128 | users { 129 | email 130 | pins { 131 | title 132 | } 133 | } 134 | } 135 | `; 136 | 137 | graphql(schema, query).then(result => 138 | console.log(JSON.stringify(result, null, 1)) 139 | ); 140 | ``` 141 | 142 | Приведенный выше пример показывает, насколько легко получить вложенные ресурсы. Как вы понимаете, выполнение предыдущего примера вернет JSON-объект с точно такими же ключами, которые были указаны в запросе. Убедитесь в этом сами, запустив команду `node query/2-fields.js` в консоли из-под директории проекта. 143 | 144 | ```bash 145 | $ node queries/2-fields.js 146 | { 147 | "data": { 148 | "users": [ 149 | { 150 | "email": "Hello World", 151 | "pins": [ 152 | { 153 | "title": "Hello World" 154 | }, 155 | { 156 | "title": "Hello World" 157 | } 158 | ] 159 | }, 160 | { 161 | "email": "Hello World", 162 | "pins": [ 163 | { 164 | "title": "Hello World" 165 | }, 166 | { 167 | "title": "Hello World" 168 | } 169 | ] 170 | } 171 | ] 172 | } 173 | } 174 | ``` 175 | 176 | ## 1.4 Несколько полей 177 | 178 | GraphQL позволяет получить несколько полей в одном запросе. В предыдущем примере вы видели, что можно запросить вложенные ресурсы, но также возможно запросить совершенно не связанные с друг другом ресурсы в одной и той же операции. 179 | 180 | ```js 181 | const { graphql } = require("graphql"); 182 | 183 | const schema = require("../schema"); 184 | 185 | const query = ` 186 | { 187 | users { 188 | email 189 | } 190 | pins { 191 | title 192 | } 193 | } 194 | `; 195 | 196 | graphql(schema, query).then(result => 197 | console.log(JSON.stringify(result, null, 1)) 198 | ); 199 | ``` 200 | 201 | Теперь вы понимаете, что GraphQL-запросы на самом деле представляют из себя получение конкретных полей объектов. Если вы выполните `node queries/3-multiple-fields.js`, то получите объект с двумя ключами: `users` и `pins`. 202 | 203 | ```bash 204 | $ node queries/3-multiple-fields.js 205 | { 206 | "data": { 207 | "users": [ 208 | { 209 | "email": "Hello World" 210 | }, 211 | { 212 | "email": "Hello World" 213 | } 214 | ], 215 | "pins": [ 216 | { 217 | "title": "Hello World" 218 | }, 219 | { 220 | "title": "Hello World" 221 | } 222 | ] 223 | } 224 | } 225 | ``` 226 | 227 | ## 1.5 Название операции 228 | 229 | До сих пор мы использовали сокращенный синтаксис запросов GraphQL, хотя вместе с ним есть более длинный синтаксис, который предоставляет больше возможностей. Более длинный синтаксис включает ключевое слово `query` и имя операции. Неоднократно, если не всегда, вы будете использовать именно такой синтаксис, поскольку он позволяет указывать переменные или использовать различные операции, такие как мутации или подписки, которые мы рассмотрим в оставшейся части книги. 230 | 231 | Вот как выглядит запрос с именем операции `GetUsers`: 232 | 233 | ```js 234 | const { graphql } = require("graphql"); 235 | 236 | const schema = require("../schema"); 237 | 238 | const query = ` 239 | query GetUsers { 240 | users { 241 | email 242 | pins { 243 | title 244 | } 245 | } 246 | } 247 | `; 248 | 249 | graphql(schema, query).then(result => 250 | console.log(JSON.stringify(result, null, 1)) 251 | ); 252 | ``` 253 | 254 | Вы можете запустить предыдущий запрос, набрав в консоли `node queries/4-operation-name.js`. Обратите внимание, что приведенная выше версия запроса работает аналогично, как и сокращенная версия. 255 | 256 | ```bash 257 | $ node queries/4-operation-name.js 258 | { 259 | "data": { 260 | "users": [ 261 | { 262 | "email": "Hello World", 263 | "pins": [ 264 | { 265 | "title": "Hello World" 266 | }, 267 | { 268 | "title": "Hello World" 269 | } 270 | ] 271 | }, 272 | { 273 | "email": "Hello World", 274 | "pins": [ 275 | { 276 | "title": "Hello World" 277 | }, 278 | { 279 | "title": "Hello World" 280 | } 281 | ] 282 | } 283 | ] 284 | } 285 | } 286 | ``` 287 | 288 | ## 1.6 Аргументы 289 | 290 | У всех полей могут быть аргументы, которые можно использовать аналогично, как и аргументы функции. Вы можете рассматривать GraphQL-поля как функции, а не свойства. Представление их в виде функций дает более четкое представление о том, что вы можете сделать с полями, передав им аргументы. 291 | 292 | Давайте предположим, например, что вы хотите запросить пин по идентификатору, запросив поле `pinById`. Можно получить пин с идентификатором `1`, передав в запрос соответствующий именованный аргумент подобным образом: 293 | 294 | ```js 295 | const { graphql } = require("graphql"); 296 | 297 | const schema = require("../schema"); 298 | 299 | const query = ` 300 | query { 301 | pinById(id: "1") { 302 | title 303 | } 304 | } 305 | `; 306 | 307 | graphql(schema, query).then(result => 308 | console.log(JSON.stringify(result, null, 1)) 309 | ); 310 | ``` 311 | 312 | Выполнение `node queries/5-arguments.js` в консоли приведёт к следующему выводу: 313 | 314 | ```bash 315 | $ node queries/5-arguments.js 316 | { 317 | "data": { 318 | "pinById": { 319 | "title": "Hello World" 320 | } 321 | } 322 | } 323 | ``` 324 | 325 | ## 1.7 Псевдонимы 326 | 327 | Что произойдет, если вы захотите запросить одно и то же поле дважды в одном запросе? Ну... вы можете достичь этого с помощью псевдонимов. Псевдонимы позволяют связать имя с полем, так что в ответе будет указан псевдоним вместо имя ключа. 328 | 329 | Псевдоним поля — это также просто, как и добавление имени поля с желаемым псевдонимом и двоеточием (:). 330 | 331 | Псевдонимы особенно полезны при запросе одного и того же поля, но с разными аргументами. Следующий запрос дважды запрашивает поле `pinById`, используя псевдонимы: первое поле будет иметь псевдоним `firstPin`, а второе поле — `secondPin`. 332 | 333 | ```js 334 | const { graphql } = require("graphql"); 335 | 336 | const schema = require("../schema"); 337 | 338 | const query = ` 339 | query { 340 | firstPin: pinById(id: "1") { 341 | title 342 | } 343 | secondPin: pinById(id: "2") { 344 | title 345 | } 346 | } 347 | `; 348 | 349 | graphql(schema, query).then(result => 350 | console.log(JSON.stringify(result, null, 1)) 351 | ); 352 | ``` 353 | 354 | Как вы видите, ответ содержит псевдонимы вместо имени поля. Проверьте сами, выполнив команду `node queries/6-aliases.js`. 355 | 356 | ```bash 357 | $ node queries/6-aliases.js 358 | { 359 | "data": { 360 | "firstPin": { 361 | "title": "Hello World" 362 | }, 363 | "secondPin": { 364 | "title": "Hello World" 365 | } 366 | } 367 | } 368 | ``` 369 | 370 | ## 1.8 Фрагменты 371 | 372 | Синтаксис GraphQL предоставляет возможность многократного использования набора полей с использованием ключевого поля `fragment`. Это язык, предназначенный для запросов полей, поэтому вполне естественно ожидать вариант для многократного использования полей в разных частях запроса. 373 | 374 | Для повторного использования поля, сначала нужно определить фрагмент, а затем поместить фрагмент в разные части запроса. 375 | 376 | Определите фрагменты, используя следующий синтаксис: `fragment [fragmentName] on [Type] { field anotherField }`. Используйте фрагменты, поместив `...[fragmentName]` в то место запроса, где вы указали бы поле. 377 | 378 | Любой примере лучше всего продемонстрирует какую-либо возможность. В следующем примере определяется фрагмент с именем `pinFields`, а затем используется дважды в запросе. 379 | 380 | ```js 381 | const { graphql } = require("graphql"); 382 | 383 | const schema = require("../schema"); 384 | 385 | const query = ` 386 | query { 387 | pins { 388 | ...pinFields 389 | } 390 | users { 391 | email 392 | pins { 393 | ...pinFields 394 | } 395 | } 396 | } 397 | fragment pinFields on Pin { 398 | title 399 | } 400 | `; 401 | 402 | graphql(schema, query).then(result => 403 | console.log(JSON.stringify(result, null, 1)) 404 | ); 405 | ``` 406 | 407 | Выполните запрос выше с помощью команды `node queries/7-fragments.js`. Попробуйте поиграть с этим фрагментом, изменив список запрашиваемых полей, и посмотрите, как измениться вывод скрипта. 408 | 409 | ```bash 410 | $ node queries/7-fragments.js 411 | { 412 | "data": { 413 | "pins": [ 414 | { 415 | "title": "Hello World" 416 | }, 417 | { 418 | "title": "Hello World" 419 | } 420 | ], 421 | "users": [ 422 | { 423 | "email": "Hello World", 424 | "pins": [ 425 | { 426 | "title": "Hello World" 427 | }, 428 | { 429 | "title": "Hello World" 430 | } 431 | ] 432 | }, 433 | { 434 | "email": "Hello World", 435 | "pins": [ 436 | { 437 | "title": "Hello World" 438 | }, 439 | { 440 | "title": "Hello World" 441 | } 442 | ] 443 | } 444 | ] 445 | } 446 | } 447 | ``` 448 | 449 | ## 1.9 Переменные 450 | 451 | Так же, как фрагменты позволяют вам повторно использовать наборы полей, переменные дают повторно использовать запросы. Используя переменные, можно указать, какие части запроса являются настраиваемыми, так что вы можете использовать запрос несколько раз, изменяя значения переменных. Используя переменные, можно создавать динамические запросы. 452 | 453 | Давайте посмотрим, как вы можете добавить переменные в пример запроса пинов по идентификатору. Можно определить переменную с именем `$id`, указать ее тип `String` и пометить ее как обязательную, поставив восклицательный знак (`!`) после названия типа. 454 | 455 | Следующий фрагмент определяет переменную `$id` в своем запросе и отправляет ее вместе со схемой и списком переменных в `graphql`. Функция `graphql` получает список переменных в качестве пятого аргумента. 456 | 457 | ```js 458 | const { graphql } = require("graphql"); 459 | 460 | const schema = require("../schema"); 461 | 462 | const query = ` 463 | query ($id: String!) { 464 | pinById(id: $id) { 465 | title 466 | } 467 | } 468 | `; 469 | 470 | graphql(schema, query, undefined, undefined, { 471 | id: "1" 472 | }).then(result => 473 | console.log(JSON.stringify(result, null, 1)) 474 | ); 475 | ``` 476 | 477 | Результат выполнения `node query / 8-variables.js` довольно ясен. 478 | 479 | ```bash 480 | $ node queries/8-variables.js 481 | { 482 | "data": { 483 | "pinById": { 484 | "title": "Hello World" 485 | } 486 | } 487 | } 488 | ``` 489 | 490 | ## 1.10 Директивы 491 | 492 | По аналогии как переменные дают возможность создавать динамические запросы путем изменения аргументов, директивы позволяют конструировать динамические запросы, которые изменяют структуру и форму их результата. 493 | 494 | Директивы возможно прикрепить к полям или фрагментам. Все директивы начинаются с символа `@`. 495 | 496 | GraphQL-серверы могут предоставлять любое количество директив, которое они пожелают, однако в спецификации GraphQL определены две обязательные директивы: `@include(if: Boolean)` и `@skip(if: Boolean)`. Первая директива включает поле только если `if` равно true, а вторая, напротив, пропускает поле, когда `if` равно true. 497 | 498 | Следующий пример показывает директивы в действии. Директива `@include` помещается в поле `pins` и параметризует значение, используя переменную с именем `$withPins`. 499 | 500 | ```js 501 | const { graphql } = require("graphql"); 502 | 503 | const schema = require("../schema"); 504 | 505 | const query = ` 506 | query ($withPins: Boolean!) { 507 | users { 508 | email 509 | pins @include(if: $withPins) { 510 | title 511 | } 512 | } 513 | } 514 | `; 515 | 516 | graphql(schema, query, undefined, undefined, { 517 | withPins: true 518 | }).then(result => 519 | console.log(JSON.stringify(result, null, 1)) 520 | ); 521 | ``` 522 | 523 | Двигайтесь дальше, выполните предыдущий пример через команду `node queries/9-directives.js`. Измените `withPins` на false, что увидеть, как изменится структура результата. 524 | 525 | ```bash 526 | $ node queries/9-directives.js 527 | { 528 | "data": { 529 | "users": [ 530 | { 531 | "email": "Hello World", 532 | "pins": [ 533 | { 534 | "title": "Hello World" 535 | }, 536 | { 537 | "title": "Hello World" 538 | } 539 | ] 540 | }, 541 | { 542 | "email": "Hello World", 543 | "pins": [ 544 | { 545 | "title": "Hello World" 546 | }, 547 | { 548 | "title": "Hello World" 549 | } 550 | ] 551 | } 552 | ] 553 | } 554 | } 555 | ``` 556 | 557 | ## 1.11 Переменные по умолчанию 558 | 559 | Синтаксис GraphQL даёт определять значения по умолчанию для переменных. Это возможно, если добавить знак равенства (=) после типа переменной. 560 | 561 | Давайте рассмотрим пример, добавив параметр по умолчанию `true` к предыдущему примеру с директивами. Значение по умолчанию для переменной позволяет вызвать функцию `graphql` в примере, не указывая значение для `withPins` в аргументе списка переменных. 562 | 563 | ```js 564 | const { graphql } = require("graphql"); 565 | 566 | const schema = require("../schema"); 567 | 568 | const query = ` 569 | query ($withPins: Boolean = true) { 570 | users { 571 | email 572 | pins @include(if: $withPins) { 573 | title 574 | } 575 | } 576 | } 577 | `; 578 | 579 | graphql(schema, query).then(result => 580 | console.log(JSON.stringify(result, null, 1)) 581 | ); 582 | ``` 583 | 584 | Выполните в консоли: `node queries/10-default-variables.js`. Обратите внимание, вывод выглядит точно так же, как и вызов `graphql` со значением `withPins`, равным `true`. 585 | 586 | ```bash 587 | $ node queries/10-default-variables.js 588 | { 589 | "data": { 590 | "users": [ 591 | { 592 | "email": "Hello World", 593 | "pins": [ 594 | { 595 | "title": "Hello World" 596 | }, 597 | { 598 | "title": "Hello World" 599 | } 600 | ] 601 | }, 602 | { 603 | "email": "Hello World", 604 | "pins": [ 605 | { 606 | "title": "Hello World" 607 | }, 608 | { 609 | "title": "Hello World" 610 | } 611 | ] 612 | } 613 | ] 614 | } 615 | } 616 | ``` 617 | 618 | ## 1.12 Встроенные фрагменты 619 | 620 | Встроенные фрагменты предусматривают способ указать список встроенных полей. В отличие от обычных фрагментов, которые должны быть определены с помощью ключевого слова `fragment`, встроенные фрагменты не нужно где-либо определять. 621 | 622 | Эти типы фрагментов полезны при запросе полей с типом `Union` или `Interface`. Эти поля могут возвращать объекты с различными полями, в зависимости от типа объекта. Вы можете использовать фрагменты, чтобы указать, какие поля возвращать, основываясь на типе объекта. 623 | 624 | Отличный случай использования встроенных фрагментов — поисковый запрос, который может возвращать объекты разных типов. В следующем фрагменте показано, как можно использовать встроенные фрагменты, чтобы получить разный набор полей из запроса `search`. Если возвращаемый объект — это `Person`, значит нужно вернуть его `email`, а если этот объект — `Pin`, то вернуть его `title`. 625 | 626 | ```js 627 | const { graphql } = require("graphql"); 628 | 629 | const schema = require("../schema"); 630 | 631 | const query = ` 632 | query ($text: String!) { 633 | search(text: $text) { 634 | ... on Person { 635 | email 636 | } 637 | ... on Pin { 638 | title 639 | } 640 | } 641 | } 642 | `; 643 | 644 | graphql(schema, query, undefined, undefined, { 645 | text: "Hello world" 646 | }).then(result => 647 | console.log(JSON.stringify(result, null, 1)) 648 | ); 649 | ``` 650 | 651 | Запустите этот пример, используя `node queries/11-inline-fragments.js`. 652 | 653 | ```bash 654 | $ node queries/11-inline-fragments.js 655 | { 656 | "data": { 657 | "search": [ 658 | { 659 | "title": "Hello World" 660 | }, 661 | { 662 | "email": "Hello World" 663 | } 664 | ] 665 | } 666 | } 667 | ``` 668 | 669 | ## 1.13 Метаполя 670 | 671 | Запросы могут запрашивать метаполя, представляющие собой специальные поля, которые содержат информацию о схеме. 672 | 673 | GraphQL позволяет получать имена типов объектов, запрашивая метаполе с именем `__typename`. 674 | 675 | Данное метаполе полезно в тех же ситуациях, где удобны встроенные фрагменты, то есть в запросах, которые могут возвращать несколько типов полей, таких как `Union` или `Interface`. 676 | 677 | Следующий фрагмент кода добавляет поле `__typename` к примеру запроса `search` из объяснения встроенных фрагментов. 678 | 679 | ```js 680 | const { graphql } = require("graphql"); 681 | 682 | const schema = require("../schema"); 683 | 684 | const query = ` 685 | query ($text: String!) { 686 | search(text: $text) { 687 | __typename 688 | ... on Person { 689 | email 690 | } 691 | ... on Pin { 692 | title 693 | } 694 | } 695 | } 696 | `; 697 | 698 | graphql(schema, query, undefined, undefined, { 699 | text: "Hello world" 700 | }).then(result => 701 | console.log(JSON.stringify(result, null, 1)) 702 | ); 703 | ``` 704 | 705 | Запустите предыдущий скрипт, выполнив в командной строке `node queries/12-meta-fields.js`. Вы увидите, что ответ содержит поле `__typename` в каждом объекте. 706 | 707 | ```bash 708 | $ node queries/12-meta-fields.js 709 | { 710 | "data": { 711 | "search": [ 712 | { 713 | "__typename": "Admin", 714 | "email": "Hello World" 715 | }, 716 | { 717 | "__typename": "Pin", 718 | "title": "Hello World" 719 | } 720 | ] 721 | } 722 | } 723 | ``` 724 | 725 | ## 1.14 Мутации 726 | 727 | Синтаксис GraphQL позволяет создавать данные с использованием ключевого слова `mutation`. Оно работает аналогично ключевому слову `query`. Поддерживаются переменные, поэтому возможно запросить конкретные поля в ответе, а также всё то, что мы разбирали ранее. В отличие от запросов, мутации не имеют сокращенных форм написания, так что, они всегда начинаются с ключевого слова `mutation`. 728 | 729 | Даже если мутации означают изменения данных, это всего лишь соглашение. Нет никакой гарантии, что серверы будут изменять данные внутри мутаций. Точно так же нельзя утверждать наверняка, что запросы содержат только изменения данных. Это соглашение похоже на соглашения из REST, предписывающие GET-запросам не иметь побочных эффектов, либо рекомендуют использовать POST-запросы для создания ресурсов. Данное соглашение не соблюдается тем или иным образом, однако вам следует придерживаться его, чтобы не преподносить неожиданные сюрпризы пользователям вашего API. 730 | 731 | Давайте посмотрим, как мутации работают на практике, отправив мутацию с именем `addPin`, представленную на примере схемы, которую мы использовали в этой главе. 732 | 733 | Вы заметите, что написание мутаций действительно похоже на написание запросов. Единственное отличие заключается в разном ключевом слове и, конечно, то, это операция предполагает изменение данных. 734 | 735 | ```js 736 | const { graphql } = require("graphql"); 737 | 738 | const schema = require("../schema"); 739 | 740 | const query = ` 741 | mutation AddPin($pin: PinInput!) { 742 | addPin(pin: $pin) { 743 | id 744 | title 745 | link 746 | image 747 | } 748 | } 749 | `; 750 | 751 | graphql(schema, query, undefined, undefined, { 752 | pin: { 753 | title: "Hello world", 754 | link: "Hello world", 755 | image: "Hello world" 756 | } 757 | }).then(result => 758 | console.log(JSON.stringify(result, null, 1)) 759 | ); 760 | ``` 761 | 762 | Запустите этот пример мутации, набрав в консоли команду `node queries/13-mutations.js`. Помните, что наша схема работает с фиктивными данными, она не имеет реальной реализации, поэтому не ожидайте каких-либо изменений данных, вызванных данной мутацией. 763 | 764 | ```bash 765 | $ node queries/13-mutations.js 766 | { 767 | "data": { 768 | "addPin": { 769 | "id": "Hello World", 770 | "title": "Hello World", 771 | "link": "Hello World", 772 | "image": "Hello World" 773 | } 774 | } 775 | } 776 | ``` 777 | 778 | Если вы запросите список пинов после последней мутации, вы заметите, что выполненная последняя мутация не создала никаких данных. Это происходит потому, что запросы в этой главе выполняются на имитированной схеме. 779 | 780 | ## 1.15 Резюме 781 | 782 | GraphQL упрощает фронтенд-разработку, предоставляя мощные возможности запросов. Это облегчает получение нескольких вложенных ресурсов в одном запросе. Извлечение минимального набора полей из ресурса также является встроенной возможностью. 783 | 784 | В следующей главе, «Моделирование данных», вы с нуля разработаете схему, которую использовали в этой главе. По сравнению с используемой схемой текущей главы, в следующей главе будет использоваться база данных в оперативной памяти для хранения схемы, и у нее не будет фиктивных значений. 785 | 786 | 787 | [^queries_note]: Термины **queries**, **mutations** и **subscriptions**, используемые в рамках этой книги, помимо основного значения являются и самостоятельными определениями, которые обозначают типы запросов на сервер: запросы, мутации и подписки, соответственно. — Здесь и далее прим. пер. -------------------------------------------------------------------------------- /manuscript/chapter-2.md: -------------------------------------------------------------------------------- 1 | # 2. Моделирование данных 2 | 3 | В предыдущей главе вы узнали, как читать и записывать данные, отправляя запросы к схеме с использованием языка запросов GraphQL. В этой главе вы научитесь, как моделировать данные, лежащие в основе запросов, используя схемы и типы. Для создания такой схемы, вы будете использовать язык определения схемы (Schema Definition Language) GraphQL (также называемый SDL, чтобы не путать с LSD). 4 | 5 | В то время как предыдущая глава была посвящена взаимодействию клиентов с серверами, используя GraphQL, в этой главе будет рассказано, как представить модель данных, которую могут использовать клиенты. 6 | 7 | Помните клон Pinterest, о котором шла речь во введении? Изучив концепции схем и типов GraphQL, к концу главы вы разработаете модель данных. 8 | 9 | ## 2.1 Схема, типы и резолверы 10 | 11 | Серверы GraphQL предоставляют свою схему для того, чтобы клиенты знали, какие доступны запросы и мутации. Для определения того, как выглядит схема, вам нужно объявить типы всех полей. Чтобы определить, как ведет себя схема, вам нужно создать функцию, которую сервер будет запускать, когда клиент запрашивает поле, — такая функция называется резолвером. Схема нуждается как в определениях типов, так и в резолверах. 12 | 13 | ![Типы и резолверы](images/types-resolvers.png) 14 | 15 | Поскольку GraphQL — это спецификация, реализованная на многих языках программирования, она предоставляет собственный язык для разработки схем, называемый SDL. Вы пишете определения типов на SDL, хотя создавать резолверы можно на любом языке, который реализует спецификацию GraphQL. Эта книга посвящена JavaScript-экосистеме GraphQL, поэтому вам предстоит все резолверы на данном языке. 16 | 17 | Схема, которую вы создадите, — это нечто большее, чем просто пример, иллюстрирующий, как писать SDL-код. Это первый шаг к разработке PinApp, пример приложения данной книги. Создаваемая схема будет отражать большинство возможностей в готовом приложении: 18 | 19 | * Авторизация с помощью магических ссылок 20 | * Возможность аутентифицированным пользователям добавлять пины 21 | * Поиск по пинам и пользователям 22 | * Список пинов 23 | 24 | Создайте собственную копию этого примера с помощью следующей ссылки: 25 | 26 | [Клонировать пример схемы](https://glitch.com/edit/#!/remix/pinapp-schema) 27 | 28 | > После клонирования внимательно следуйте инструкциям в `README.md`. Файл README этого проекта сообщает вам создать переменные окружения в специальном для этого файле `.env`. 29 | 30 | Имейте в виду, что эта схема не распространяется через протокол HTTP. Она доступна со скриптами, использующими `graphql-js`. Следующая глава покажет вам, как добавить HTTP-слой в эту схему с помощью Apollo Server. 31 | 32 | В следующем разделе вы поймете, как создавать схемы, используя функцию `makeExecutableSchema`. 33 | 34 | ## 2.2 Схемы 35 | 36 | Создание схемы происходит путём сочетания определений типов и резолверов. Существует удобный пакет [`graphql-tools`](https://github.com/apollographql/graphql-tools), предоставляющий функцию `makeExecutableSchema`. Предыдущая глава содержала много вызовов `graphql(query, schema)`. Все существующие примеры отправляют запросы согласно схемы, сгенерированной с помощью функции `makeExecutableSchema`. 37 | 38 | Откройте файл `schema.js` в примере проекта, который вы только что склонировали, чтобы узнать, как можно создать схему. 39 | 40 | ```js 41 | const { makeExecutableSchema } = require("graphql-tools"); 42 | const { importSchema } = require("graphql-import"); 43 | 44 | const typeDefs = importSchema("schema.graphql"); 45 | const resolvers = require("./resolvers"); 46 | 47 | const schema = makeExecutableSchema({ 48 | typeDefs, 49 | resolvers 50 | }); 51 | 52 | module.exports = schema; 53 | ``` 54 | 55 | Как видите, этот файл создает схему с типами из файла `schema.graphql` и резолверами из файла `resolvers.js`. В следующих двух разделах вы научитесь, как создавать определения типов и резолверы. 56 | 57 | ## 2.3 Определения типов 58 | 59 | В этом разделе вы научитесь тому, как писать типы GraphQL, используя SDL. Тип — это просто представление объекта в вашей схеме. Объекты, как и во многих других языках программирования, могут иметь много полей. 60 | 61 | > Все примеры в этом разделе можно найти в файле `schema.graphql` 62 | 63 | Определить тип объекта можно подобным образом: 64 | 65 | ```graphql 66 | type Pin { 67 | title: String! 68 | link: String! 69 | image: String! 70 | id: String! 71 | user_id: String! 72 | } 73 | ``` 74 | 75 | Как видно, можно определить тип полей после имени поля. В случае `Pin`, у всех его полей указан тип `String` и все они являются обязательными, поскольку заканчиваются восклицательным знаком (!). 76 | 77 | GraphQL определяет два специальных типа объектов — `Query` и `Mutation`. Они особенные, потому что они определяют точки входа в схему. Быть точкой входа в схему означает, что клиенты GraphQL должны начинать свои запросы с одного или нескольких полей из `Query`. 78 | 79 | ```graphql 80 | type Query { 81 | pins: [Pin] 82 | pinById(id: String!): Pin 83 | users: [User] 84 | me: User 85 | search(text: String): [SearchResult] 86 | } 87 | ``` 88 | 89 | Как вы, наверное, заметили, у типов объектов могут быть аргументы. Каждое поле имеет базовую функцию (называемую резолвером), которая выполняется перед возвратом собственного значения, поэтому имеет смысл рассматривать аргументы поля по аналогии с тем, как мы размышляем над аргументами функции. 90 | 91 | Еще один новый элемент в предыдущем `Query` — это модификатор типа List. Возможно заключить поля в квадратные скобки, чтобы указать их как списки. 92 | 93 | Спецификация GraphQL определяет, что все схемы должны иметь тип `Query`, а также необязательно тип `Mutation`. Вот так выглядит тип `Mutation` в PinApp: 94 | 95 | ```graphql 96 | type Mutation { 97 | addPin(pin: PinInput!): Pin 98 | sendShortLivedToken(email: String!): Boolean 99 | createLongLivedToken(token: String!): String 100 | } 101 | ``` 102 | 103 | Обратите внимание, что поле `addPin` имеет аргумент `pin` с указанным типом `PinInput`, а у двух остальных полей есть аргументы типа `String`. Вы не можете передавать аргументы типа `Object` в качестве аргументов, разрешено передавать только скалярные типы, а также типы `Input`. 104 | 105 | Скалярные типы не могут иметь вложенные поля, они представляют собой листья[^leaves] схемы. Это встроенные скалярные типы в GraphQL: 106 | [^leaves]: Элементы самого нижнего уровня в древовидном представлении иерархии 107 | 108 | * `Int` 109 | * `Float` 110 | * `String` 111 | * `Boolean` 112 | * `ID` 113 | 114 | Некоторые реализации GraphQL позволяют определять пользовательские скалярные типы. Это означает, что есть возможность создавать собственные скаляры, такие как `Date` или `JSON`. 115 | 116 | Вы можете определить специальный вид скаляров, используя перечислимые типы (`enum`). Перечисления — специальные скалярные типы, потому что они ограничены фиксированным набором значений. 117 | 118 | Вот таким образом выглядит перечислимый тип: 119 | 120 | ```graphql 121 | enum PinStatus { 122 | DELETED 123 | HIDDEN 124 | VISIBLE 125 | } 126 | ``` 127 | 128 | Типы `Input` работает почти так же, как объекты. Внутри них могут быть поля, но разница в том, что такие поля не могут иметь аргументов и также тип `Object`. 129 | 130 | Вот как определяется нестандартный тип `PinInput`: 131 | 132 | ```graphql 133 | input PinInput { 134 | title: String! 135 | link: String! 136 | image: String! 137 | } 138 | ``` 139 | 140 | GraphQL позволяет также определять типы `Interface` и `Union`. Они полезны, когда вам нужно вернуть объект, который может состоять из нескольких разных типов. 141 | 142 | Можно воспользоваться интерфейсами, когда есть разные типы, имеющие общие поля между собой. Типичный случай использования будет представлять тип `User`. 143 | 144 | ```graphql 145 | interface Person { 146 | id: String! 147 | email: String! 148 | pins: [Pin] 149 | } 150 | 151 | type User implements Person { 152 | id: String! 153 | email: String! 154 | pins: [Pin] 155 | } 156 | 157 | type Admin implements Person { 158 | id: String! 159 | email: String! 160 | pins: [Pin] 161 | } 162 | ``` 163 | 164 | В случае, если вам нужен тип, который представляет разные типы без общих полей между собой, в вашем распоряжении есть тип `Union`. Типичная операция, которая возвращает такой тип, — это поиск: 165 | 166 | ```graphql 167 | union SearchResult = User | Admin | Pin 168 | 169 | type Query { 170 | # ... 171 | search(text: String): [SearchResult] 172 | } 173 | ``` 174 | 175 | Вот как выглядит полная версия `schema.graphql`: 176 | 177 | ```graphql 178 | type Pin { 179 | title: String! 180 | link: String! 181 | image: String! 182 | id: String! 183 | user_id: String! 184 | } 185 | 186 | input PinInput { 187 | title: String! 188 | link: String! 189 | image: String! 190 | } 191 | 192 | interface Person { 193 | id: String! 194 | email: String! 195 | pins: [Pin] 196 | } 197 | 198 | type User implements Person { 199 | id: String! 200 | email: String! 201 | pins: [Pin] 202 | } 203 | 204 | type Admin implements Person { 205 | id: String! 206 | email: String! 207 | pins: [Pin] 208 | } 209 | 210 | union SearchResult = User | Admin | Pin 211 | 212 | type Query { 213 | pins: [Pin] 214 | pinById(id: String!): Pin 215 | users: [User] 216 | me: User 217 | search(text: String): [SearchResult] 218 | } 219 | 220 | type Mutation { 221 | addPin(pin: PinInput!): Pin 222 | sendShortLivedToken(email: String!): Boolean 223 | createLongLivedToken(token: String!): String 224 | } 225 | ``` 226 | 227 | Как вы узнали из предыдущего раздела, схема состоит из определений типов и резолверов. И поскольку сейчас, когда вы знаете, как выглядят определения типов, пришло время узнать про резолверы. 228 | 229 | ## 2.4 Резолверы 230 | 231 | Резолверы — это функции, которые запускаются каждый раз, когда запрос запрашивает поле. Когда реализация GraphQL получает запрос, она выполняет резолвер для каждого поля. Если резолвер возвращает поле типа `Object`, то GraphQL запускает резолвер-функцию этого поля. Когда все резолверы возвращают скалярные значения, цепочка замыкается, и запрос получает готовый JSON-результат. 232 | 233 | Поскольку GraphQL не привязан к какой-либо технологии баз данных, поэтому реализация резолвера полностью зависит от вас. Все функции в файле `resolvers.js` используют обычный JS-объект, служащий базой данных в оперативной памяти, однако уже в следующей главе вы узнаете, как выполнить миграцию в базу данных Postgres. 234 | 235 | Вы можете организовать резолверы любым способом, в зависимости от ваших потребностей. Примеры этой книги стремятся держать резолвер-функции простыми, а также разделить доступ к базе данных с помощью бизнес-логики. Это простой случай применения старого доброго принципа [разделения ответственности](https://ru.wikipedia.org/wiki/%D0%A0%D0%B0%D0%B7%D0%B4%D0%B5%D0%BB%D0%B5%D0%BD%D0%B8%D0%B5_%D0%BE%D1%82%D0%B2%D0%B5%D1%82%D1%81%D1%82%D0%B2%D0%B5%D0%BD%D0%BD%D0%BE%D1%81%D1%82%D0%B8). 236 | 237 | Давайте посмотрим, как выглядит `resolvers.js`: 238 | 239 | ```js 240 | const { 241 | addPin, 242 | createShortLivedToken, 243 | sendShortLivedToken, 244 | createLongLivedToken, 245 | createUser 246 | } = require("./business-logic"); 247 | 248 | const database = { 249 | users: {}, 250 | pins: {} 251 | }; 252 | 253 | const resolvers = { 254 | Query: { 255 | pins: () => Object.values(database.pins), 256 | users: () => Object.values(database.users), 257 | search: (_, { text }) => { 258 | return [ 259 | ...Object.values(database.pins).filter(pin => 260 | pin.title.includes(text) 261 | ), 262 | ...Object.values(database.users).filter(user => 263 | user.email.includes(text) 264 | ) 265 | ]; 266 | } 267 | }, 268 | Mutation: { 269 | addPin: async (_, { pin }, { user }) => { 270 | const { 271 | user: updatedUser, 272 | pin: createdPin 273 | } = await addPin(user, pin); 274 | database.pins[createdPin.id] = createdPin; 275 | database.users[user.id] = updatedUser; 276 | return createdPin; 277 | }, 278 | sendShortLivedToken: (_, { email }) => { 279 | let user; 280 | const userExists = Object.values(database.users).find( 281 | u => u.email === user.email 282 | ); 283 | if (userExists) { 284 | user = userExists; 285 | } else { 286 | user = createUser(email); 287 | database.users[user.id] = user; 288 | } 289 | const token = createShortLivedToken(user); 290 | return sendShortLivedToken(email, token); 291 | }, 292 | createLongLivedToken: (_, { token }) => { 293 | return createLongLivedToken(token); 294 | } 295 | }, 296 | Person: { 297 | __resolveType: person => { 298 | if (person.admin) { 299 | return "Admin"; 300 | } 301 | return "User"; 302 | } 303 | }, 304 | User: { 305 | pins({ id }) { 306 | return Object.values(database.pins).filter( 307 | pin => pin.user_id === id 308 | ); 309 | } 310 | }, 311 | SearchResult: { 312 | __resolveType: searchResult => { 313 | if (searchResult.admin) { 314 | return "Admin"; 315 | } 316 | if (searchResult.email) { 317 | return "User"; 318 | } 319 | return "Pin"; 320 | } 321 | } 322 | }; 323 | 324 | module.exports = resolvers; 325 | ``` 326 | 327 | В этом случае не все поля `Query` и `Mutation` имеют соответствующий резолвер. Если у поля нет резовлера, оно будет иметь значение `null`. Конечно, это только для демонстрационных целей. Ваши клиенты API не будут очень довольны запросами, которые всегда возвращают неопределённое значение. 328 | 329 | Можно заметить, что большая часть логики в полях `Query` и `Mutations` состоит из функций, определенных в файле `business-logic.js`. Содержимое функций — чаще всего доступ к данным и вызовы методов из модуля бизнес-логики. 330 | 331 | Некоторые из типов в файле `resolvers.js` имеют методы `__resolveType`. Это метод, который использует `makeExecutableSchema` из `graphql-tools`. Он определяет тип объектов типа, которые имеют `Union` или `Interface`. 332 | 333 | Вы можете попробовать схему этого примера, если откроете консоль склонированного примера и запустив в ней `node queries.js`. Этот скрипт имитирует пользователя, который сначала создает токен аутентификации и отправляет его, чтобы можно добавить новый пин. 334 | 335 | ```bash 336 | $ node queries 337 | API Token: 338 | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9... 339 | { 340 | "data": { 341 | "addPin": { 342 | "id": "f5220ee1-bfeb-48a0-be9f-c63d055b8139", 343 | "title": "Hello world", 344 | "link": "http://graphql.college/fullstack-graphql", 345 | "image": "http://graphql.college/fullstack-graphql", 346 | "user_id": "75c16079-b3ef-43f0-a352-ae03f2488baa" 347 | } 348 | } 349 | } 350 | ``` 351 | 352 | Не бойтесь экспериментировать, изменяя различные резолвер-функции и наблюдая за тем, как изменяется конечный результат. Вы также можете создавать различные запросы, теперь, когда вы уже знаете, какие запросы и мутации предоставляет ваша схема. 353 | 354 | ## 2.5 Резюме 355 | 356 | Вы узнали, как создавать GraphQL-схемы. Вы написали определения типов с использованием SDL, а также резолверы, используя JavaScript. Схема, созданная в рамках этой главы, доступна скриптами, использующими `graphql-js`. 357 | 358 | В следующей главе вы узнаете, как создавать HTTP API с помощью GraphQL. Вы добавите различные слои, составляющие сервер GraphQL, поверх схемы GraphQL. Этот API будет иметь несколько дополнительных уровней, включая HTTP, базу данных и аутентификацию. 359 | 360 | -------------------------------------------------------------------------------- /manuscript/chapter-3.md: -------------------------------------------------------------------------------- 1 | # 3. API-интерфейсы GraphQL 2 | 3 | HTTP-сервер — наиболее распространённый способ предоставить схему GraphQL. Создание API-интерфейсов GraphQL — это гораздо больше, чем просто проектирование схем. В этой главе вы узнаете, как создавать надежные, многоуровневые API-интерфейсы GraphQL. 4 | 5 | ![Сервер](images/server.png) 6 | 7 | Вы узнаете, как предоставлять GraphQL-схемы с помощью Apollo Server. Как подключить ваши резолверы к базе данных. Вы добавите аутентификацию по электронной почте в собственный API. Наконец, вы научитесь, как организовать исходный код по функциональным возможностям. 8 | 9 | ![Слои сервера](images/server-layers.png) 10 | 11 | Все этапы этой главы имеют соответствующий проект, который можно склонировать, чтобы попробовать на практике. 12 | 13 | Давайте начнем с изучения того, как создать API, используя Apollo Server. 14 | 15 | ## 3.1 Сервер 16 | 17 | Apollo Server — это сервер с открытым исходном кодом, совместимый со спецификацией GraphQL. Это готовый к работе в продакшене, простой в настройке способ представления GraphQL-схем, так чтобы HTTP-клиенты могли их использовать. 18 | 19 | ![HTTP](images/http.png) 20 | 21 | Вы уже создали схему с использованием `graphql-tools` в предыдущей главе, поэтому публично представить её с помощью Apollo Server не составляет никакого труда. 22 | 23 | ```js 24 | const { ApolloServer } = require("apollo-server"); 25 | 26 | const schema = require("./schema"); 27 | 28 | const server = new ApolloServer({ schema }); 29 | 30 | server.listen().then(({ url }) => { 31 | console.log(`🚀 Server ready at ${url}`); 32 | }); 33 | ``` 34 | 35 | Действительно просто! Достаточно вызова функции `server.listen()` и у вас есть работающий API для GraphQL. Склонируйте следующий пример проекта, чтобы у вас была собственная копия проекта. 36 | 37 | [Клонировать пример сервера](https://glitch.com/edit/#!/remix/pinapp-server) 38 | 39 | Нажмите кнопку «Show» в левом верхнем углу экрана для открытия включенного в комплект GraphQL-клиента — [GraphQL Playground](https://github.com/prismagraphql/graphql-playground). Это больше, чем просто клиент GraphQL, скорее что-то вроде IDE. У этого инструмента есть автозаполнение запроса, документация GraphQL-схемы, а также хранение всех выполненных запросов, что позволяет использовать в будущем. 40 | 41 | ![GraphQL Playground](images/graphql-playground.png) 42 | 43 | Теперь, когда вы развернули собственный API-сервер GraphQL, пришло время добавить сохранение данных, используя базу данных. 44 | 45 | ## 3.2 База данных 46 | 47 | API-интерфейсы GraphQL могут быть работать с любым источником данных. Они могут использовать базы данных SQL, NoSQL, базы данных в оперативной памяти или даже использовать конечные точки HTTP. 48 | 49 | ![База данных](images/database.png) 50 | 51 | В этой главе вы подключите PinApp к базе данных SQLite, используя коннектор базы данных [Knex](http://knexjs.org). Knex — это построитель SQL-запросов, который может взаимодействовать со многими базами данных SQL, такими как SQLite3, MySQL, Postgres и др. 52 | 53 | Склонируйте текущую итерацию приложения PinApp, чтобы вы могли следовать по тексту этого раздела, работая с собственной копией проекта. 54 | 55 | [Клонировать пример базы данных](https://glitch.com/edit/#!/remix/pinapp-database) 56 | 57 | > Не забывайте следовать инструкциям по началу работы в файле README проекта 58 | 59 | Поскольку все взаимодействия с базами данных происходят в файле `resolvers.js`, давайте начнем с этого файла. 60 | 61 | Получить набор записей с помощью `select()`. Например, получить список пинов можно следующим образом: 62 | 63 | ```js 64 | pins: () => database("pins").select(), 65 | ``` 66 | 67 | Вы можете объединить в цепочку вызовов функции Knex. Например, можно отфильтровать результаты из `select()`, добавив его вызов с функцией `where()`. 68 | 69 | ```js 70 | search: (_, { text }) => { 71 | return Promise.all([ 72 | database("users") 73 | .select() 74 | .where("email", "like", `%${text}%`), 75 | database("pins") 76 | .select() 77 | .where("title", "like", `%${text}%`) 78 | ]); 79 | }; 80 | ``` 81 | 82 | Еще одна полезная функция, которую предоставляет Knex, — это `insert()`. Она позволит создавать объекты в базе данных. Вот так выглядит мутация `addPin` при использовании `insert`. 83 | 84 | ```js 85 | addPin: async (_, { pin }, { token }) => { 86 | const [user] = await authorize(token); 87 | const { user: updatedUser, pin: createdPin } = await addPin(user, pin); 88 | await database("pins").insert(createdPin); 89 | return createdPin; 90 | }, 91 | ``` 92 | 93 | Файл `database.js` создает экземпляр Knex и экспортирует в качестве модуля. Это простой файл, который создает экземпляр Knex с конфигурационными значениями из файла с именем `knexfile.js`. 94 | 95 | ```js 96 | const database = require("knex")(require("./knexfile")); 97 | 98 | module.exports = database; 99 | ``` 100 | 101 | У Knex имеется интерфейс командной строки, предоставляющий несколько утилит для создания миграций, заполнения данными баз данных и многое другое. Утилита CLI считывает конфигурацию из `knexfile.js`. Файл конфигурации PinApp выглядит так: 102 | 103 | ```js 104 | module.exports = { 105 | client: "sqlite3", 106 | connection: { 107 | filename: ".data/database.sqlite" 108 | } 109 | }; 110 | ``` 111 | 112 | > [Glitch](https://glitch.com) позволяет сохранять данные в директории `.data`. Именно по этой причине файл `database.sqlite` находится в этой директории. 113 | 114 | Последний шаг, необходимый для использования SQL-файла, — создание схемы базы данных. Knex может генерировать файлы миграции, используя собственный инструмент командной строки. 115 | 116 | Выполнение `npx knex migrate:make create_users_table` создаст файл с именем `[date]_create_users_table.js` в директории `.migrations`. Этот файл экспортирует два метода — `up` и `down`. Эти методы являются своего рода заполнителями, которые необходимо заполнить согласно ваших конкретным потребностям. В данном случае таблица пользователей будет иметь два поля: `id` и `email`. У обоих полей указан тип `string`, а поле `id` задано как первичный ключ. 117 | 118 | ```js 119 | exports.up = function(knex) { 120 | return knex.schema.createTable("users", function(table) { 121 | table.string("id").primary(); 122 | table.string("email"); 123 | }); 124 | }; 125 | 126 | exports.down = function(knex) { 127 | return knex.schema.dropTable("users"); 128 | }; 129 | ``` 130 | 131 | В склонированном проекте есть еще одна миграция — `[date]_create_pins_migration`. Эта миграция определяет пять строковых (`string`) полей: `id`, `title`, `link`, `image` и `pin_id`. 132 | 133 | ```js 134 | exports.up = function(knex) { 135 | return knex.schema.createTable("pins", function(table) { 136 | table.string("id").primary(); 137 | table.string("title"); 138 | table.string("link"); 139 | table.string("image"); 140 | table 141 | .string("user_id") 142 | .references("id") 143 | .inTable("users") 144 | .onDelete("CASCADE") 145 | .onUpdate("CASCADE"); 146 | }); 147 | }; 148 | 149 | exports.down = function(knex) { 150 | return knex.schema.dropTable("pins"); 151 | }; 152 | ``` 153 | 154 | Выполните `npm run setup-db` для применения всех миграций базы данных. Этот скрипт определен в ключе `scripts` файла `package.json`: 155 | 156 | ```json 157 | "setup-db": "knex migrate:latest"` 158 | ``` 159 | 160 | Изучение SQL выходит за рамки книги: если вы хотите правильно изучить этот язык, лучше всего прочитать соответствующую книгу. Построитель запросов Knex отлично работает с базами данных SQL, а еще у него есть отличная [документация](http://knexjs.org). Обратитесь к ней, если вы хотите узнать больше про данный инструмент. 161 | 162 | ## 3.3 Аутентификация 163 | 164 | Один из самых часто задаваемых вопросов при создании API-интерфейсов с использованием GraphQL: «Куда поместить аутентификацию и авторизацию?». Это должно быть в слое GraphQL? Или на уровне базы данных? А может быть в бизнес-логики? Несмотря на то, что ответ зависит от контекста того, какой API вы создаете, распространенный способ решения этой проблемы — поместить аутентификацию и авторизацию на бизнес-уровне. Размещение кода, связанного с аутентификацией, на бизнес-уровне — это [подход Facebook](https://dev-blog.apollodata.com/graphql-at-facebook-by-dan-schafer-38d65ef075af). 165 | 166 | ![Бизнес-логика](images/business-logic.png) 167 | 168 | Вы можете реализовать аутентификацию несколькими способами, что полностью соответствует вашим потребностям. Этот раздел покажет, как добавить аутентификацию по электронной почте в PinApp. 169 | 170 | Аутентификация на основе электронной почты состоит из поля для ввода электронной почты. Как только пользователи укажут электронную почту, им придёт ссылка на приложение, в которой будет содержаться аутентификационный временный токен. Если пользователи перейдут в приложение с использованием действительного токена, то значит такому пользователю можно доверять (предполагаем, что почта пользователя подтверждена). А далее действительный токен будет заменен на токен аутентификации с более продолжительным сроком действия. 171 | 172 | Самое большое преимущество подобной системы аутентификации, в отличие от старой доброй аутентификации по паролю, заключается в том, что вам вообще не нужно заниматься паролями. То, что мы не храним пароли также означает, что не требуется принимать крайних мер безопасности для их защиты. Еще это значит, что вашим пользователям не нужно заходить на очередной сайт, который просит их создать новый пароль. 173 | 174 | ```gherkin 175 | Feature: Email based authentication 176 | 177 | Scenario: Send magic link 178 | Given a user enters his email address 179 | When he/she submits the form 180 | Then he/she should receive an email with a link to the app that contains his token 181 | 182 | Scenario: Verify email 183 | Given a user receives an email with a magic link 184 | When he/she clicks the link 185 | Then he/she should see a loading screen 186 | When the app verifies the token 187 | Then he/she should see an email confirmation message 188 | ``` 189 | 190 | Говоря в терминах GraphQL, оба эти действия (сценария) отражаются на мутациях в соответствующей GraphQL-схеме — `sendShortLivedToken` и `createLongLivedToken`. Первое действие получает в качестве аргумента электронное письмо типа `String`. Второе действие получает действительный токен, а возвращает новый токен. 191 | 192 | ```graphql 193 | type Mutation { 194 | # ... 195 | sendShortLivedToken(email: String!): Boolean 196 | createLongLivedToken(token: String!): String 197 | } 198 | ``` 199 | 200 | Склонируйте этот проект для того, чтобы следить за ходом внедрения аутентификации по электронной почте. 201 | 202 | [Склонировать пример аутентификации по электронной почте](https://glitch.com/edit/#!/remix/pinapp-email-authentication) 203 | 204 | Теперь давайте проанализируем, как выглядят резолверы, связанные с электронной почтой. 205 | 206 | Резолвер `sendShortLivedToken` должен проверить, существует ли пользователь, соответствующий электронной почте. Если он не существует, он должен вставить его в базу данных. После этого он должен создать токен с небольшим сроком действия и отправить его на электронную почту пользователя. 207 | 208 | ```js 209 | sendShortLivedToken: async (_, { email }) => { 210 | let user; 211 | const userExists = await database("users") 212 | .select() 213 | .where({ email }); 214 | if (userExists.length) { 215 | user = userExists[0]; 216 | } else { 217 | user = createUser(email); 218 | await database("users").insert(user); 219 | } 220 | const token = createShortLivedToken(user); 221 | return sendShortLivedToken(email, token); 222 | }; 223 | ``` 224 | 225 | Этот резолвер использует две функции из файла `business-logic.js` — `createShortLivedToken` и `sendShortLivedToken`. 226 | 227 | Первый создает токен, используя функцию `jsonwebtoken` из NPM-пакета [`sign`](https://github.com/auth0/node-jsonwebtoken#jwtsignpayload-secretorprivatekey-options-callback). У этого токена срок действия ограничен пятью минутами. 228 | 229 | ```js 230 | const createShortLivedToken = ({ email, id }) => { 231 | return jsonwebtoken.sign( 232 | { id, email }, 233 | process.env.SECRET, 234 | { 235 | expiresIn: "5m" 236 | } 237 | ); 238 | }; 239 | ``` 240 | 241 | Вторая функция `sendShortLivedToken` использует функцию, определенную в файле `email.js`, под названием `sendMail`. 242 | 243 | ```js 244 | const sendShortLivedToken = (email, token) => { 245 | return sendMail({ 246 | from: '"Julian" ', 247 | to: email, 248 | text: `${process.env.APP_URL}/verify?token=${token}`, 249 | html: `Authenticate`, 252 | subject: "Auth token" 253 | }); 254 | }; 255 | ``` 256 | 257 | Для отправки почты воспользуемся пакетом `nodemailer`. Эта библиотека позволяет отправлять электронные письма через SMTP-сервер. Самый простой способ создать почтовый сервер для разработки — [Ethereal](https://ethereal.email/messages. Это фиктивный почтовый сервис, разработанный создателями Nodemailer, является очень простым способом создания SMTP-службы для разработки. Разумеется, если вы хотите отправлять реальные электронные письма, вам следует использовать реальный сервис SMTP. [Sendgrid](https://sendgrid.com/) предлагает отличный бесплатный план. 258 | 259 | ```js 260 | const nodemailer = require("nodemailer"); 261 | 262 | const transporter = nodemailer.createTransport({ 263 | host: "smtp.ethereal.email", 264 | port: 587, 265 | auth: { 266 | user: process.env.MAIL_USER, 267 | pass: process.env.MAIL_PASSWORD 268 | } 269 | }); 270 | 271 | function sendMail({ from, to, subject, text, html }) { 272 | const mailOptions = { 273 | from, 274 | to, 275 | subject, 276 | text, 277 | html 278 | }; 279 | return new Promise((resolve, reject) => { 280 | transporter.sendMail(mailOptions, (error, info) => { 281 | if (error) { 282 | return reject(error); 283 | } 284 | resolve(info); 285 | }); 286 | }); 287 | } 288 | 289 | module.exports = sendMail; 290 | ``` 291 | 292 | Реализация `createLongLivedToken` намного проще, чем `sendShortLivedToken`. Первый резолвер использует функцию из файла `business-logic.js`, проверяющая токен, переданный в качестве аргумента. Если токен действителен, функция создает токен с окончанием срока действия, равный тридцать дней. 293 | 294 | ```js 295 | const createLongLivedToken = token => { 296 | try { 297 | const { id, email } = jsonwebtoken.verify( 298 | token, 299 | process.env.SECRET 300 | ); 301 | const longLivedToken = jsonwebtoken.sign( 302 | { id, email }, 303 | process.env.SECRET, 304 | { expiresIn: "30 days" } 305 | ); 306 | return Promise.resolve(longLivedToken); 307 | } catch (error) { 308 | console.error(error); 309 | throw error; 310 | } 311 | }; 312 | ``` 313 | 314 | Двигайтесь дальше и сконфигурируйте склонированный проект в соответствии с вашей учетной записью Ethereal. Как только всё будет настроено, зайдите в GraphQL Playground, нажав кнопку «Show», и попробуйте авторизоваться, используя собственную электронную почту (или любую другую, так как Ethereal перехватывает все отправленные письма :D). 315 | 316 | ## 3.4 Организация файлов 317 | 318 | В этом разделе вы узнаете, как использовать `graphql-import` для организации API-интерфейсов Node.js GraphQL по функциональным возможностям. Импорт GraphQL позволяет импортировать и экспортировать определения типов в GraphQL SDL. 319 | 320 | На текущий момент все файлы в образце репозитория сгруппированы по ролям, но подобный не очень хорошо подходит для больших проектов. Сейчас все резолверы определены в файле `resolvers.js`, определения типов — в файле `schema.graphql`, а вся бизнес-логика — в файле b`business-logic.js`. По мере того, как проекты становятся все больше и больше, эти три файла станут слишком большими и неуправляемыми. 321 | 322 | Текущая структура файла проекта выглядит таким образом: 323 | 324 | ![Текущая файловая структура](images/current-file-structure.png) 325 | 326 | Вы собираетесь разделить `schema.graphql`, `resolvers.js` и `business-logic.js` на три функциональные возможности: `authentication`, `pins` и `search`. Окончательная структура каталогов будет такой, как показано ниже: 327 | 328 | ![Окончательная файловая структура](images/final-file-structure.png) 329 | 330 | Склонируйте проект, если хотите посмотреть на окончательную версию. 331 | 332 | [Клонировать пример организации файлов](https://glitch.com/edit/#!/remix/pinapp-files) 333 | 334 | Основной точкой входа схемы GraphQL по-прежнему будет файл `schema.graphql`. Разница в том, что в нем не будут содержаться какие-либо определения типов, а вместо этого импортировать все типы из файла `schema.graphql` в каждой директории функциональной возможности. Основная схема будет импортировать остальные схемы, используя оператор `import`, предоставленный `graphql-import`. Его синтаксис: `# import * from "module-name.graphql"`. 335 | 336 | ```graphql 337 | # import * from "authentication/schema.graphql" 338 | # import * from "pins/schema.graphql" 339 | # import * from "search/schema.graphql" 340 | ``` 341 | 342 | Такой способ импорта GraphQL SDL возможен, поскольку файл `schema.js` загружает `schema.graphql` следующим фрагментом кода: 343 | 344 | ```js 345 | const { importSchema } = require("graphql-import"); 346 | 347 | const typeDefs = importSchema("schema.graphql"); 348 | // ... 349 | ``` 350 | 351 | Подобное схеме, главная точка входа для всех резолверов останется прежней. Это по-прежнему будет `resolvers.js`. Node.js уже предоставляет способ импорта и экспорта файлов с помощью `require`, поэтому вам не потребуется использовать дополнительную библиотеку. Даже если этот файл не нуждается в дополнительной библиотеке для импорта модулей, он использует библиотеку для объединения импортируемых резолверов. Можно писать на чистом JavaScript-коде, чтобы достичь аналогичного результата, однако `lodash.merge` — это отличный способ объединить множества JavaScript-объектов. 352 | 353 | ```js 354 | const merge = require("lodash.merge"); 355 | 356 | const searchResolvers = require("./search/resolvers.js"); 357 | const authenticationResolvers = require("./authentication/resolvers.js"); 358 | const pinsResolvers = require("./pins/resolvers.js"); 359 | 360 | const resolvers = merge( 361 | searchResolvers, 362 | authenticationResolvers, 363 | pinsResolvers 364 | ); 365 | 366 | module.exports = resolvers; 367 | ``` 368 | 369 | В завершение изменения файловой структуры, разделите `business-logic.js`, `resolvers.js` и `schema.graphql`. Разделите файл `business-logic.js` на `authentication/index.js` и `pins/index.js`. Разделите `resolvers.js` на`authentication/resolvers.js`, `pins/resolvers.js` и `search/resolvers.js`. И напоследок разделите `schema.graphql` на три новые директории. 370 | 371 | Всё! Использование файловой структуры, основанной на функциональных возможностях — это масштабируемый способ организации кода. Такой подход может быть излишним для небольших проектов, но он с лихвой окупается в больших проектах. 372 | 373 | ## 3.5 Резюме 374 | 375 | Вы узнали, как создать API на GraphQL, используя Apollo Server. Начав с простой GraphQL-схемы, вы узнали, как обернуть эту схему HTTP-слоем при помощи ApolloServer. Вы добавили слой базы данных, воспользовавшись Knex, а также аутентификацию по электронной почты с применением Nodemailer. Наконец, вы организовали свой проект по функциональным возможностям с использованием GraphQL Import. 376 | 377 | В следующей главе вы научитесь, как создавать GraphQL-клиенты на примере Apollo Client, а также сделаете фронтенд на React, который взаимодействует с только что созданным API GraphQL. 378 | 379 | -------------------------------------------------------------------------------- /manuscript/chapter-4.md: -------------------------------------------------------------------------------- 1 | # 4. GraphQL clients 2 | 3 | In this chapter you will learn how to build a GraphQL client using React and Apollo GraphQL. 4 | 5 | ![Client](images/client.png) 6 | 7 | You will start with a bare-bones React application, and transform it step-by-step into a GraphQL powered Pinterest clone. The first step will be making an app with all state stored in the client. After that you will learn how to add a GraphQL library called Apollo Client. Finally, you will learn how to easily fetch and store data in the GraphQL server using React Apollo's `Query` and `Mutation` components. 8 | 9 | Let's start with the initial version of PinApp. 10 | 11 | ## 4.1 Initial React client 12 | 13 | The first version of PinApp's client consists of a single `App` component that renders a `div` that says "PinApp". The project's setup is pretty standard, since it's based on the super popular [`create-react-app`](https://github.com/facebook/create-react-app). Here is the complete source code for `src/App.js`: 14 | 15 | ```js 16 | import React from "react"; 17 | 18 | export default class App extends React.Component { 19 | render() { 20 | return
PinApp
; 21 | } 22 | } 23 | ``` 24 | 25 | Remix this project to create your own copy of it: 26 | 27 | [Remix initial React client](https://glitch.com/edit/#!/remix/pinapp-initial) 28 | 29 | The next section will teach you how to create a client side version of PinApp. 30 | 31 | ## 4.2 Client side state 32 | 33 | This section will teach you how to create a working, client-side only version of PinApp. To achieve this, you will use a library called [`pinapp-components`](https://github.com/GraphQLCollege/pinapp-components). This library exports a `Container` component, a `Nav` component and also five Page components, `PinListPage`, `LoginPage`, `VerifyPage`, `AddPinPage` and `ProfilePage`. To get to know all of these components, see them live in [the playground](https://graphqlcollege.github.io/pinapp-components). 34 | 35 | These components expose a well defined API via their props. This customization enables you to use them to create a version of PinApp using only local state and passing it via props. Using the same components, but passing different props, you will create a version of PinApp backed by the GraphQL API you created in the previous chapter. 36 | 37 | Following is a brief description of all components. 38 | 39 | `Container` sets up PinApp's styling and routing configuration. Render it as the first in your component hierarchy. It only receives children as props. 40 | 41 | `Nav` renders a list of actions as the app's footer. Actions are links to `/`, `/upload-pin` and `/profile`. 42 | 43 | The rest of the components define a page each. 44 | 45 | `PinListPage` renders a list of pins in the `/` URL. It receives just one argument, `pins`. `pins` is an array that contains a list of pins. Pins must be object with `title`, `image` and `link` properties. All three properties must be Strings. 46 | 47 | ![PinListPage](images/pinlist-page.png) 48 | 49 | `LoginPage` sets up the `/login` URL. It receives only one prop, `authenticate`. It is a function that will run when the user clicks "login". This function receives a string as an argument, which contains an email that the user entered. 50 | 51 | ![LoginPage](images/login-page.png) 52 | 53 | `VerifyPage` sets up a screen in the `/verify?token={token}` URL. This component receives one prop called `verify`. It is a function that will run when the component mounts. This function passes a string argument which contains the token that the user entered in the URL's query string. 54 | 55 | ![VerifyPage](images/verify-page.png) 56 | 57 | `AddPinPage` renders a form to create a pin in the `/upload-pin` URL. This component receives two props, `authenticated` and `addPin`. `authenticated` is a boolean. `addPin` is a function that will run when the user clicks "Save". It receives a pin object as argument. 58 | 59 | ![AddPinPage](images/addpin-page.png) 60 | 61 | The last page component is `ProfilePage`. It shows the users' profile in the `/profile` URL. It receives three props, `user`, `authenticated` and `logout`. `user` is an object with an `email` property. `authenticated` is a boolean. `logout` is a function that will run when the user clicks "Logout". It does not receive any arguments. 62 | 63 | ![ProfilePage](images/profile-page.png) 64 | 65 | Now let's talk about how state management. The app will have three keys in state. It will hold an array of `pins`, a boolean called `authenticated` and a `user` object. The `App` component will have three functions that directly modify this state, called `addPin`, `verify` and `logout`. To simulate authentication, it will have an `authenticate` function that always authenticates the user. This `App` component will pass down its state and functions as props to the components from `pinapp-components`. 66 | 67 | The first thing you need to do is add `"pinapp-components": "^1.0.1"` to the `"dependencies"` key in your `package.json`. 68 | 69 | After adding `pinapp-components` as a dependency, modify `src/App.js` to look like this: 70 | 71 | ```js 72 | import React from "react"; 73 | import { 74 | Container, 75 | Nav, 76 | PinListPage, 77 | AddPinPage, 78 | LoginPage, 79 | VerifyPage, 80 | ProfilePage 81 | } from "pinapp-components"; 82 | 83 | export default class App extends React.Component { 84 | state = { pins: [], authenticated: false, user: null }; 85 | addPin = pin => { 86 | this.setState(({ pins }) => ({ 87 | pins: pins.concat([pin]) 88 | })); 89 | }; 90 | verify = () => { 91 | return success().then(token => 92 | this.setState({ 93 | authenticated: true, 94 | user: { email: "name@example.com" } 95 | }) 96 | ); 97 | }; 98 | authenticate = () => { 99 | return Promise.resolve({}); 100 | }; 101 | logout = () => { 102 | this.setState({ authenticated: false, user: null }); 103 | }; 104 | render() { 105 | return ( 106 | 107 | 108 | 112 | 113 | 114 | 119 |