From 298fcceb7e1e15add92f65828e1a4c923a05e090 Mon Sep 17 00:00:00 2001 From: Crowdin Bot Date: Sat, 25 Apr 2026 16:09:30 +0000 Subject: [PATCH 1/5] New Crowdin translations by GitHub Action --- .../advanced/developing-template-engines.md | 43 ++ .../docs/de/4x/guide/behind-proxies.mdx | 102 +++ src/content/docs/de/4x/guide/debugging.mdx | 124 ++++ .../docs/de/4x/guide/error-handling.mdx | 312 ++++++++ .../de/4x/guide/overriding-express-api.md | 68 ++ src/content/docs/de/4x/guide/routing.mdx | 418 +++++++++++ .../docs/de/4x/guide/using-middleware.mdx | 299 ++++++++ .../de/4x/guide/using-template-engines.mdx | 63 ++ .../docs/de/4x/guide/writing-middleware.mdx | 239 ++++++ .../docs/de/4x/starter/basic-routing.mdx | 67 ++ src/content/docs/de/4x/starter/examples.mdx | 45 ++ src/content/docs/de/4x/starter/faq.md | 90 +++ src/content/docs/de/4x/starter/generator.mdx | 125 ++++ .../docs/de/4x/starter/hello-world.mdx | 54 ++ src/content/docs/de/4x/starter/installing.mdx | 50 ++ .../docs/de/4x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/de/5x/guide/behind-proxies.mdx | 102 +++ src/content/docs/de/5x/guide/debugging.mdx | 124 ++++ .../docs/de/5x/guide/error-handling.mdx | 312 ++++++++ .../de/5x/guide/overriding-express-api.md | 68 ++ src/content/docs/de/5x/guide/routing.mdx | 418 +++++++++++ .../docs/de/5x/guide/using-middleware.mdx | 299 ++++++++ .../de/5x/guide/using-template-engines.mdx | 63 ++ .../docs/de/5x/guide/writing-middleware.mdx | 209 ++++++ .../docs/de/5x/starter/basic-routing.mdx | 67 ++ src/content/docs/de/5x/starter/examples.mdx | 49 ++ src/content/docs/de/5x/starter/faq.md | 90 +++ src/content/docs/de/5x/starter/generator.mdx | 125 ++++ .../docs/de/5x/starter/hello-world.mdx | 54 ++ src/content/docs/de/5x/starter/installing.mdx | 41 ++ .../docs/de/5x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/es/4x/guide/behind-proxies.mdx | 102 +++ src/content/docs/es/4x/guide/debugging.mdx | 123 ++++ .../docs/es/4x/guide/error-handling.mdx | 312 ++++++++ .../es/4x/guide/overriding-express-api.md | 68 ++ src/content/docs/es/4x/guide/routing.mdx | 418 +++++++++++ .../docs/es/4x/guide/using-middleware.mdx | 299 ++++++++ .../es/4x/guide/using-template-engines.mdx | 63 ++ .../docs/es/4x/guide/writing-middleware.mdx | 239 ++++++ .../docs/es/4x/starter/basic-routing.mdx | 67 ++ src/content/docs/es/4x/starter/examples.mdx | 45 ++ src/content/docs/es/4x/starter/faq.md | 90 +++ src/content/docs/es/4x/starter/generator.mdx | 125 ++++ .../docs/es/4x/starter/hello-world.mdx | 54 ++ src/content/docs/es/4x/starter/installing.mdx | 50 ++ .../docs/es/4x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/es/5x/guide/behind-proxies.mdx | 102 +++ src/content/docs/es/5x/guide/debugging.mdx | 123 ++++ .../docs/es/5x/guide/error-handling.mdx | 312 ++++++++ .../es/5x/guide/overriding-express-api.md | 68 ++ src/content/docs/es/5x/guide/routing.mdx | 418 +++++++++++ .../docs/es/5x/guide/using-middleware.mdx | 299 ++++++++ .../es/5x/guide/using-template-engines.mdx | 63 ++ .../docs/es/5x/guide/writing-middleware.mdx | 209 ++++++ .../docs/es/5x/starter/basic-routing.mdx | 67 ++ src/content/docs/es/5x/starter/examples.mdx | 49 ++ src/content/docs/es/5x/starter/faq.md | 90 +++ src/content/docs/es/5x/starter/generator.mdx | 125 ++++ .../docs/es/5x/starter/hello-world.mdx | 54 ++ src/content/docs/es/5x/starter/installing.mdx | 41 ++ .../docs/es/5x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/fr/4x/guide/behind-proxies.mdx | 102 +++ src/content/docs/fr/4x/guide/debugging.mdx | 124 ++++ .../docs/fr/4x/guide/error-handling.mdx | 312 ++++++++ .../fr/4x/guide/overriding-express-api.md | 68 ++ src/content/docs/fr/4x/guide/routing.mdx | 418 +++++++++++ .../docs/fr/4x/guide/using-middleware.mdx | 299 ++++++++ .../fr/4x/guide/using-template-engines.mdx | 63 ++ .../docs/fr/4x/guide/writing-middleware.mdx | 239 ++++++ .../docs/fr/4x/starter/basic-routing.mdx | 67 ++ src/content/docs/fr/4x/starter/examples.mdx | 45 ++ src/content/docs/fr/4x/starter/faq.md | 90 +++ src/content/docs/fr/4x/starter/generator.mdx | 125 ++++ .../docs/fr/4x/starter/hello-world.mdx | 54 ++ src/content/docs/fr/4x/starter/installing.mdx | 50 ++ .../docs/fr/4x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/fr/5x/guide/behind-proxies.mdx | 102 +++ src/content/docs/fr/5x/guide/debugging.mdx | 124 ++++ .../docs/fr/5x/guide/error-handling.mdx | 312 ++++++++ .../fr/5x/guide/overriding-express-api.md | 68 ++ src/content/docs/fr/5x/guide/routing.mdx | 418 +++++++++++ .../docs/fr/5x/guide/using-middleware.mdx | 299 ++++++++ .../fr/5x/guide/using-template-engines.mdx | 63 ++ .../docs/fr/5x/guide/writing-middleware.mdx | 209 ++++++ .../docs/fr/5x/starter/basic-routing.mdx | 67 ++ src/content/docs/fr/5x/starter/examples.mdx | 49 ++ src/content/docs/fr/5x/starter/faq.md | 90 +++ src/content/docs/fr/5x/starter/generator.mdx | 125 ++++ .../docs/fr/5x/starter/hello-world.mdx | 54 ++ src/content/docs/fr/5x/starter/installing.mdx | 41 ++ .../docs/fr/5x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/it/4x/guide/behind-proxies.mdx | 102 +++ src/content/docs/it/4x/guide/debugging.mdx | 124 ++++ .../docs/it/4x/guide/error-handling.mdx | 312 ++++++++ .../it/4x/guide/overriding-express-api.md | 68 ++ src/content/docs/it/4x/guide/routing.mdx | 418 +++++++++++ .../docs/it/4x/guide/using-middleware.mdx | 299 ++++++++ .../it/4x/guide/using-template-engines.mdx | 63 ++ .../docs/it/4x/guide/writing-middleware.mdx | 239 ++++++ .../docs/it/4x/starter/basic-routing.mdx | 67 ++ src/content/docs/it/4x/starter/examples.mdx | 45 ++ src/content/docs/it/4x/starter/faq.md | 90 +++ src/content/docs/it/4x/starter/generator.mdx | 125 ++++ .../docs/it/4x/starter/hello-world.mdx | 54 ++ src/content/docs/it/4x/starter/installing.mdx | 50 ++ .../docs/it/4x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/it/5x/guide/behind-proxies.mdx | 102 +++ src/content/docs/it/5x/guide/debugging.mdx | 124 ++++ .../docs/it/5x/guide/error-handling.mdx | 312 ++++++++ .../it/5x/guide/overriding-express-api.md | 68 ++ src/content/docs/it/5x/guide/routing.mdx | 418 +++++++++++ .../docs/it/5x/guide/using-middleware.mdx | 299 ++++++++ .../it/5x/guide/using-template-engines.mdx | 63 ++ .../docs/it/5x/guide/writing-middleware.mdx | 209 ++++++ .../docs/it/5x/starter/basic-routing.mdx | 67 ++ src/content/docs/it/5x/starter/examples.mdx | 49 ++ src/content/docs/it/5x/starter/faq.md | 90 +++ src/content/docs/it/5x/starter/generator.mdx | 125 ++++ .../docs/it/5x/starter/hello-world.mdx | 54 ++ src/content/docs/it/5x/starter/installing.mdx | 41 ++ .../docs/it/5x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/ja/4x/guide/behind-proxies.mdx | 101 +++ src/content/docs/ja/4x/guide/debugging.mdx | 124 ++++ .../docs/ja/4x/guide/error-handling.mdx | 312 ++++++++ .../ja/4x/guide/overriding-express-api.md | 68 ++ src/content/docs/ja/4x/guide/routing.mdx | 418 +++++++++++ .../docs/ja/4x/guide/using-middleware.mdx | 299 ++++++++ .../ja/4x/guide/using-template-engines.mdx | 63 ++ .../docs/ja/4x/guide/writing-middleware.mdx | 239 ++++++ .../docs/ja/4x/starter/basic-routing.mdx | 67 ++ src/content/docs/ja/4x/starter/examples.mdx | 45 ++ src/content/docs/ja/4x/starter/faq.md | 90 +++ src/content/docs/ja/4x/starter/generator.mdx | 125 ++++ .../docs/ja/4x/starter/hello-world.mdx | 54 ++ src/content/docs/ja/4x/starter/installing.mdx | 50 ++ .../docs/ja/4x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/ja/5x/guide/behind-proxies.mdx | 101 +++ src/content/docs/ja/5x/guide/debugging.mdx | 124 ++++ .../docs/ja/5x/guide/error-handling.mdx | 312 ++++++++ .../ja/5x/guide/overriding-express-api.md | 68 ++ src/content/docs/ja/5x/guide/routing.mdx | 418 +++++++++++ .../docs/ja/5x/guide/using-middleware.mdx | 299 ++++++++ .../ja/5x/guide/using-template-engines.mdx | 63 ++ .../docs/ja/5x/guide/writing-middleware.mdx | 209 ++++++ .../docs/ja/5x/starter/basic-routing.mdx | 67 ++ src/content/docs/ja/5x/starter/examples.mdx | 49 ++ src/content/docs/ja/5x/starter/faq.md | 90 +++ src/content/docs/ja/5x/starter/generator.mdx | 125 ++++ .../docs/ja/5x/starter/hello-world.mdx | 54 ++ src/content/docs/ja/5x/starter/installing.mdx | 41 ++ .../docs/ja/5x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/ko/4x/guide/behind-proxies.mdx | 102 +++ src/content/docs/ko/4x/guide/debugging.mdx | 124 ++++ .../docs/ko/4x/guide/error-handling.mdx | 312 ++++++++ .../ko/4x/guide/overriding-express-api.md | 68 ++ src/content/docs/ko/4x/guide/routing.mdx | 418 +++++++++++ .../docs/ko/4x/guide/using-middleware.mdx | 299 ++++++++ .../ko/4x/guide/using-template-engines.mdx | 63 ++ .../docs/ko/4x/guide/writing-middleware.mdx | 239 ++++++ .../docs/ko/4x/starter/basic-routing.mdx | 67 ++ src/content/docs/ko/4x/starter/examples.mdx | 45 ++ src/content/docs/ko/4x/starter/faq.md | 90 +++ src/content/docs/ko/4x/starter/generator.mdx | 125 ++++ .../docs/ko/4x/starter/hello-world.mdx | 54 ++ src/content/docs/ko/4x/starter/installing.mdx | 50 ++ .../docs/ko/4x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/ko/5x/guide/behind-proxies.mdx | 102 +++ src/content/docs/ko/5x/guide/debugging.mdx | 124 ++++ .../docs/ko/5x/guide/error-handling.mdx | 312 ++++++++ .../ko/5x/guide/overriding-express-api.md | 68 ++ src/content/docs/ko/5x/guide/routing.mdx | 418 +++++++++++ .../docs/ko/5x/guide/using-middleware.mdx | 299 ++++++++ .../ko/5x/guide/using-template-engines.mdx | 63 ++ .../docs/ko/5x/guide/writing-middleware.mdx | 209 ++++++ .../docs/ko/5x/starter/basic-routing.mdx | 67 ++ src/content/docs/ko/5x/starter/examples.mdx | 49 ++ src/content/docs/ko/5x/starter/faq.md | 90 +++ src/content/docs/ko/5x/starter/generator.mdx | 125 ++++ .../docs/ko/5x/starter/hello-world.mdx | 54 ++ src/content/docs/ko/5x/starter/installing.mdx | 41 ++ .../docs/ko/5x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/pt-br/4x/guide/behind-proxies.mdx | 102 +++ src/content/docs/pt-br/4x/guide/debugging.mdx | 124 ++++ .../docs/pt-br/4x/guide/error-handling.mdx | 312 ++++++++ .../pt-br/4x/guide/overriding-express-api.md | 68 ++ src/content/docs/pt-br/4x/guide/routing.mdx | 418 +++++++++++ .../docs/pt-br/4x/guide/using-middleware.mdx | 299 ++++++++ .../pt-br/4x/guide/using-template-engines.mdx | 63 ++ .../pt-br/4x/guide/writing-middleware.mdx | 239 ++++++ .../docs/pt-br/4x/starter/basic-routing.mdx | 67 ++ .../docs/pt-br/4x/starter/examples.mdx | 45 ++ src/content/docs/pt-br/4x/starter/faq.md | 90 +++ .../docs/pt-br/4x/starter/generator.mdx | 127 ++++ .../docs/pt-br/4x/starter/hello-world.mdx | 54 ++ .../docs/pt-br/4x/starter/installing.mdx | 49 ++ .../docs/pt-br/4x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/pt-br/5x/guide/behind-proxies.mdx | 102 +++ src/content/docs/pt-br/5x/guide/debugging.mdx | 124 ++++ .../docs/pt-br/5x/guide/error-handling.mdx | 312 ++++++++ .../pt-br/5x/guide/overriding-express-api.md | 68 ++ src/content/docs/pt-br/5x/guide/routing.mdx | 418 +++++++++++ .../docs/pt-br/5x/guide/using-middleware.mdx | 299 ++++++++ .../pt-br/5x/guide/using-template-engines.mdx | 63 ++ .../pt-br/5x/guide/writing-middleware.mdx | 209 ++++++ .../docs/pt-br/5x/starter/basic-routing.mdx | 67 ++ .../docs/pt-br/5x/starter/examples.mdx | 49 ++ src/content/docs/pt-br/5x/starter/faq.md | 90 +++ .../docs/pt-br/5x/starter/generator.mdx | 127 ++++ .../docs/pt-br/5x/starter/hello-world.mdx | 54 ++ .../docs/pt-br/5x/starter/installing.mdx | 41 ++ .../docs/pt-br/5x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/zh-tw/4x/guide/behind-proxies.mdx | 102 +++ src/content/docs/zh-tw/4x/guide/debugging.mdx | 124 ++++ .../docs/zh-tw/4x/guide/error-handling.mdx | 312 ++++++++ .../zh-tw/4x/guide/overriding-express-api.md | 68 ++ src/content/docs/zh-tw/4x/guide/routing.mdx | 418 +++++++++++ .../docs/zh-tw/4x/guide/using-middleware.mdx | 299 ++++++++ .../zh-tw/4x/guide/using-template-engines.mdx | 63 ++ .../zh-tw/4x/guide/writing-middleware.mdx | 239 ++++++ .../docs/zh-tw/4x/starter/basic-routing.mdx | 67 ++ .../docs/zh-tw/4x/starter/examples.mdx | 45 ++ src/content/docs/zh-tw/4x/starter/faq.md | 90 +++ .../docs/zh-tw/4x/starter/generator.mdx | 125 ++++ .../docs/zh-tw/4x/starter/hello-world.mdx | 54 ++ .../docs/zh-tw/4x/starter/installing.mdx | 50 ++ .../docs/zh-tw/4x/starter/static-files.mdx | 82 +++ .../advanced/developing-template-engines.md | 43 ++ .../docs/zh-tw/5x/guide/behind-proxies.mdx | 102 +++ src/content/docs/zh-tw/5x/guide/debugging.mdx | 124 ++++ .../docs/zh-tw/5x/guide/error-handling.mdx | 312 ++++++++ .../zh-tw/5x/guide/overriding-express-api.md | 68 ++ src/content/docs/zh-tw/5x/guide/routing.mdx | 418 +++++++++++ .../docs/zh-tw/5x/guide/using-middleware.mdx | 299 ++++++++ .../zh-tw/5x/guide/using-template-engines.mdx | 63 ++ .../zh-tw/5x/guide/writing-middleware.mdx | 209 ++++++ .../docs/zh-tw/5x/starter/basic-routing.mdx | 67 ++ .../docs/zh-tw/5x/starter/examples.mdx | 49 ++ src/content/docs/zh-tw/5x/starter/faq.md | 90 +++ .../docs/zh-tw/5x/starter/generator.mdx | 125 ++++ .../docs/zh-tw/5x/starter/hello-world.mdx | 54 ++ .../docs/zh-tw/5x/starter/installing.mdx | 41 ++ .../docs/zh-tw/5x/starter/static-files.mdx | 82 +++ .../de/advanced/best-practice-performance.md | 305 ++++++++ .../de/advanced/best-practice-security.mdx | 276 +++++++ .../advanced/healthcheck-graceful-shutdown.md | 28 + .../pages/de/advanced/security-updates.mdx | 87 +++ .../pages/de/guide/database-integration.mdx | 503 +++++++++++++ src/content/pages/de/guide/migrating-4.mdx | 661 +++++++++++++++++ src/content/pages/de/guide/migrating-5.mdx | 678 ++++++++++++++++++ src/content/pages/de/resources/glossary.mdx | 61 ++ src/content/pages/de/resources/utils.md | 22 + src/content/pages/de/support.md | 23 + .../es/advanced/best-practice-performance.md | 305 ++++++++ .../es/advanced/best-practice-security.mdx | 276 +++++++ .../advanced/healthcheck-graceful-shutdown.md | 28 + .../pages/es/advanced/security-updates.mdx | 87 +++ .../pages/es/guide/database-integration.mdx | 503 +++++++++++++ src/content/pages/es/guide/migrating-4.mdx | 662 +++++++++++++++++ src/content/pages/es/guide/migrating-5.mdx | 678 ++++++++++++++++++ src/content/pages/es/resources/glossary.mdx | 61 ++ src/content/pages/es/resources/utils.md | 22 + src/content/pages/es/support.md | 23 + .../fr/advanced/best-practice-performance.md | 305 ++++++++ .../fr/advanced/best-practice-security.mdx | 276 +++++++ .../advanced/healthcheck-graceful-shutdown.md | 28 + .../pages/fr/advanced/security-updates.mdx | 87 +++ .../pages/fr/guide/database-integration.mdx | 503 +++++++++++++ src/content/pages/fr/guide/migrating-4.mdx | 661 +++++++++++++++++ src/content/pages/fr/guide/migrating-5.mdx | 678 ++++++++++++++++++ src/content/pages/fr/resources/glossary.mdx | 61 ++ src/content/pages/fr/resources/utils.md | 22 + src/content/pages/fr/support.md | 23 + .../it/advanced/best-practice-performance.md | 305 ++++++++ .../it/advanced/best-practice-security.mdx | 276 +++++++ .../advanced/healthcheck-graceful-shutdown.md | 28 + .../pages/it/advanced/security-updates.mdx | 87 +++ .../pages/it/guide/database-integration.mdx | 503 +++++++++++++ src/content/pages/it/guide/migrating-4.mdx | 662 +++++++++++++++++ src/content/pages/it/guide/migrating-5.mdx | 678 ++++++++++++++++++ src/content/pages/it/resources/glossary.mdx | 61 ++ src/content/pages/it/resources/utils.md | 22 + src/content/pages/it/support.md | 23 + .../ja/advanced/best-practice-performance.md | 305 ++++++++ .../ja/advanced/best-practice-security.mdx | 276 +++++++ .../advanced/healthcheck-graceful-shutdown.md | 28 + .../pages/ja/advanced/security-updates.mdx | 87 +++ .../pages/ja/guide/database-integration.mdx | 503 +++++++++++++ src/content/pages/ja/guide/migrating-4.mdx | 662 +++++++++++++++++ src/content/pages/ja/guide/migrating-5.mdx | 678 ++++++++++++++++++ src/content/pages/ja/resources/glossary.mdx | 61 ++ src/content/pages/ja/resources/utils.md | 22 + src/content/pages/ja/support.md | 23 + .../ko/advanced/best-practice-performance.md | 305 ++++++++ .../ko/advanced/best-practice-security.mdx | 276 +++++++ .../advanced/healthcheck-graceful-shutdown.md | 28 + .../pages/ko/advanced/security-updates.mdx | 87 +++ .../pages/ko/guide/database-integration.mdx | 503 +++++++++++++ src/content/pages/ko/guide/migrating-4.mdx | 662 +++++++++++++++++ src/content/pages/ko/guide/migrating-5.mdx | 678 ++++++++++++++++++ src/content/pages/ko/resources/glossary.mdx | 61 ++ src/content/pages/ko/resources/utils.md | 22 + src/content/pages/ko/support.md | 23 + .../advanced/best-practice-performance.md | 305 ++++++++ .../pt-br/advanced/best-practice-security.mdx | 276 +++++++ .../advanced/healthcheck-graceful-shutdown.md | 28 + .../pages/pt-br/advanced/security-updates.mdx | 87 +++ .../pt-br/guide/database-integration.mdx | 503 +++++++++++++ src/content/pages/pt-br/guide/migrating-4.mdx | 662 +++++++++++++++++ src/content/pages/pt-br/guide/migrating-5.mdx | 678 ++++++++++++++++++ .../pages/pt-br/resources/glossary.mdx | 61 ++ src/content/pages/pt-br/resources/utils.md | 22 + src/content/pages/pt-br/support.md | 23 + .../advanced/best-practice-performance.md | 305 ++++++++ .../zh-tw/advanced/best-practice-security.mdx | 276 +++++++ .../advanced/healthcheck-graceful-shutdown.md | 28 + .../pages/zh-tw/advanced/security-updates.mdx | 87 +++ .../zh-tw/guide/database-integration.mdx | 503 +++++++++++++ src/content/pages/zh-tw/guide/migrating-4.mdx | 662 +++++++++++++++++ src/content/pages/zh-tw/guide/migrating-5.mdx | 678 ++++++++++++++++++ .../pages/zh-tw/resources/glossary.mdx | 61 ++ src/content/pages/zh-tw/resources/utils.md | 22 + src/content/pages/zh-tw/support.md | 23 + src/i18n/ui/de.json | 125 ++-- src/i18n/ui/es.json | 147 ++-- src/i18n/ui/fr.json | 141 ++-- src/i18n/ui/it.json | 125 ++-- src/i18n/ui/ja.json | 141 ++-- src/i18n/ui/ko.json | 253 ++++--- src/i18n/ui/pt-br.json | 161 ++--- src/i18n/ui/zh-tw.json | 255 ++++--- 344 files changed, 56435 insertions(+), 686 deletions(-) create mode 100644 src/content/docs/de/4x/advanced/developing-template-engines.md create mode 100644 src/content/docs/de/4x/guide/behind-proxies.mdx create mode 100644 src/content/docs/de/4x/guide/debugging.mdx create mode 100644 src/content/docs/de/4x/guide/error-handling.mdx create mode 100644 src/content/docs/de/4x/guide/overriding-express-api.md create mode 100644 src/content/docs/de/4x/guide/routing.mdx create mode 100644 src/content/docs/de/4x/guide/using-middleware.mdx create mode 100644 src/content/docs/de/4x/guide/using-template-engines.mdx create mode 100644 src/content/docs/de/4x/guide/writing-middleware.mdx create mode 100644 src/content/docs/de/4x/starter/basic-routing.mdx create mode 100644 src/content/docs/de/4x/starter/examples.mdx create mode 100644 src/content/docs/de/4x/starter/faq.md create mode 100644 src/content/docs/de/4x/starter/generator.mdx create mode 100644 src/content/docs/de/4x/starter/hello-world.mdx create mode 100644 src/content/docs/de/4x/starter/installing.mdx create mode 100644 src/content/docs/de/4x/starter/static-files.mdx create mode 100644 src/content/docs/de/5x/advanced/developing-template-engines.md create mode 100644 src/content/docs/de/5x/guide/behind-proxies.mdx create mode 100644 src/content/docs/de/5x/guide/debugging.mdx create mode 100644 src/content/docs/de/5x/guide/error-handling.mdx create mode 100644 src/content/docs/de/5x/guide/overriding-express-api.md create mode 100644 src/content/docs/de/5x/guide/routing.mdx create mode 100644 src/content/docs/de/5x/guide/using-middleware.mdx create mode 100644 src/content/docs/de/5x/guide/using-template-engines.mdx create mode 100644 src/content/docs/de/5x/guide/writing-middleware.mdx create mode 100644 src/content/docs/de/5x/starter/basic-routing.mdx create mode 100644 src/content/docs/de/5x/starter/examples.mdx create mode 100644 src/content/docs/de/5x/starter/faq.md create mode 100644 src/content/docs/de/5x/starter/generator.mdx create mode 100644 src/content/docs/de/5x/starter/hello-world.mdx create mode 100644 src/content/docs/de/5x/starter/installing.mdx create mode 100644 src/content/docs/de/5x/starter/static-files.mdx create mode 100644 src/content/docs/es/4x/advanced/developing-template-engines.md create mode 100644 src/content/docs/es/4x/guide/behind-proxies.mdx create mode 100644 src/content/docs/es/4x/guide/debugging.mdx create mode 100644 src/content/docs/es/4x/guide/error-handling.mdx create mode 100644 src/content/docs/es/4x/guide/overriding-express-api.md create mode 100644 src/content/docs/es/4x/guide/routing.mdx create mode 100644 src/content/docs/es/4x/guide/using-middleware.mdx create mode 100644 src/content/docs/es/4x/guide/using-template-engines.mdx create mode 100644 src/content/docs/es/4x/guide/writing-middleware.mdx create mode 100644 src/content/docs/es/4x/starter/basic-routing.mdx create mode 100644 src/content/docs/es/4x/starter/examples.mdx create mode 100644 src/content/docs/es/4x/starter/faq.md create mode 100644 src/content/docs/es/4x/starter/generator.mdx create mode 100644 src/content/docs/es/4x/starter/hello-world.mdx create mode 100644 src/content/docs/es/4x/starter/installing.mdx create mode 100644 src/content/docs/es/4x/starter/static-files.mdx create mode 100644 src/content/docs/es/5x/advanced/developing-template-engines.md create mode 100644 src/content/docs/es/5x/guide/behind-proxies.mdx create mode 100644 src/content/docs/es/5x/guide/debugging.mdx create mode 100644 src/content/docs/es/5x/guide/error-handling.mdx create mode 100644 src/content/docs/es/5x/guide/overriding-express-api.md create mode 100644 src/content/docs/es/5x/guide/routing.mdx create mode 100644 src/content/docs/es/5x/guide/using-middleware.mdx create mode 100644 src/content/docs/es/5x/guide/using-template-engines.mdx create mode 100644 src/content/docs/es/5x/guide/writing-middleware.mdx create mode 100644 src/content/docs/es/5x/starter/basic-routing.mdx create mode 100644 src/content/docs/es/5x/starter/examples.mdx create mode 100644 src/content/docs/es/5x/starter/faq.md create mode 100644 src/content/docs/es/5x/starter/generator.mdx create mode 100644 src/content/docs/es/5x/starter/hello-world.mdx create mode 100644 src/content/docs/es/5x/starter/installing.mdx create mode 100644 src/content/docs/es/5x/starter/static-files.mdx create mode 100644 src/content/docs/fr/4x/advanced/developing-template-engines.md create mode 100644 src/content/docs/fr/4x/guide/behind-proxies.mdx create mode 100644 src/content/docs/fr/4x/guide/debugging.mdx create mode 100644 src/content/docs/fr/4x/guide/error-handling.mdx create mode 100644 src/content/docs/fr/4x/guide/overriding-express-api.md create mode 100644 src/content/docs/fr/4x/guide/routing.mdx create mode 100644 src/content/docs/fr/4x/guide/using-middleware.mdx create mode 100644 src/content/docs/fr/4x/guide/using-template-engines.mdx create mode 100644 src/content/docs/fr/4x/guide/writing-middleware.mdx create mode 100644 src/content/docs/fr/4x/starter/basic-routing.mdx create mode 100644 src/content/docs/fr/4x/starter/examples.mdx create mode 100644 src/content/docs/fr/4x/starter/faq.md create mode 100644 src/content/docs/fr/4x/starter/generator.mdx create mode 100644 src/content/docs/fr/4x/starter/hello-world.mdx create mode 100644 src/content/docs/fr/4x/starter/installing.mdx create mode 100644 src/content/docs/fr/4x/starter/static-files.mdx create mode 100644 src/content/docs/fr/5x/advanced/developing-template-engines.md create mode 100644 src/content/docs/fr/5x/guide/behind-proxies.mdx create mode 100644 src/content/docs/fr/5x/guide/debugging.mdx create mode 100644 src/content/docs/fr/5x/guide/error-handling.mdx create mode 100644 src/content/docs/fr/5x/guide/overriding-express-api.md create mode 100644 src/content/docs/fr/5x/guide/routing.mdx create mode 100644 src/content/docs/fr/5x/guide/using-middleware.mdx create mode 100644 src/content/docs/fr/5x/guide/using-template-engines.mdx create mode 100644 src/content/docs/fr/5x/guide/writing-middleware.mdx create mode 100644 src/content/docs/fr/5x/starter/basic-routing.mdx create mode 100644 src/content/docs/fr/5x/starter/examples.mdx create mode 100644 src/content/docs/fr/5x/starter/faq.md create mode 100644 src/content/docs/fr/5x/starter/generator.mdx create mode 100644 src/content/docs/fr/5x/starter/hello-world.mdx create mode 100644 src/content/docs/fr/5x/starter/installing.mdx create mode 100644 src/content/docs/fr/5x/starter/static-files.mdx create mode 100644 src/content/docs/it/4x/advanced/developing-template-engines.md create mode 100644 src/content/docs/it/4x/guide/behind-proxies.mdx create mode 100644 src/content/docs/it/4x/guide/debugging.mdx create mode 100644 src/content/docs/it/4x/guide/error-handling.mdx create mode 100644 src/content/docs/it/4x/guide/overriding-express-api.md create mode 100644 src/content/docs/it/4x/guide/routing.mdx create mode 100644 src/content/docs/it/4x/guide/using-middleware.mdx create mode 100644 src/content/docs/it/4x/guide/using-template-engines.mdx create mode 100644 src/content/docs/it/4x/guide/writing-middleware.mdx create mode 100644 src/content/docs/it/4x/starter/basic-routing.mdx create mode 100644 src/content/docs/it/4x/starter/examples.mdx create mode 100644 src/content/docs/it/4x/starter/faq.md create mode 100644 src/content/docs/it/4x/starter/generator.mdx create mode 100644 src/content/docs/it/4x/starter/hello-world.mdx create mode 100644 src/content/docs/it/4x/starter/installing.mdx create mode 100644 src/content/docs/it/4x/starter/static-files.mdx create mode 100644 src/content/docs/it/5x/advanced/developing-template-engines.md create mode 100644 src/content/docs/it/5x/guide/behind-proxies.mdx create mode 100644 src/content/docs/it/5x/guide/debugging.mdx create mode 100644 src/content/docs/it/5x/guide/error-handling.mdx create mode 100644 src/content/docs/it/5x/guide/overriding-express-api.md create mode 100644 src/content/docs/it/5x/guide/routing.mdx create mode 100644 src/content/docs/it/5x/guide/using-middleware.mdx create mode 100644 src/content/docs/it/5x/guide/using-template-engines.mdx create mode 100644 src/content/docs/it/5x/guide/writing-middleware.mdx create mode 100644 src/content/docs/it/5x/starter/basic-routing.mdx create mode 100644 src/content/docs/it/5x/starter/examples.mdx create mode 100644 src/content/docs/it/5x/starter/faq.md create mode 100644 src/content/docs/it/5x/starter/generator.mdx create mode 100644 src/content/docs/it/5x/starter/hello-world.mdx create mode 100644 src/content/docs/it/5x/starter/installing.mdx create mode 100644 src/content/docs/it/5x/starter/static-files.mdx create mode 100644 src/content/docs/ja/4x/advanced/developing-template-engines.md create mode 100644 src/content/docs/ja/4x/guide/behind-proxies.mdx create mode 100644 src/content/docs/ja/4x/guide/debugging.mdx create mode 100644 src/content/docs/ja/4x/guide/error-handling.mdx create mode 100644 src/content/docs/ja/4x/guide/overriding-express-api.md create mode 100644 src/content/docs/ja/4x/guide/routing.mdx create mode 100644 src/content/docs/ja/4x/guide/using-middleware.mdx create mode 100644 src/content/docs/ja/4x/guide/using-template-engines.mdx create mode 100644 src/content/docs/ja/4x/guide/writing-middleware.mdx create mode 100644 src/content/docs/ja/4x/starter/basic-routing.mdx create mode 100644 src/content/docs/ja/4x/starter/examples.mdx create mode 100644 src/content/docs/ja/4x/starter/faq.md create mode 100644 src/content/docs/ja/4x/starter/generator.mdx create mode 100644 src/content/docs/ja/4x/starter/hello-world.mdx create mode 100644 src/content/docs/ja/4x/starter/installing.mdx create mode 100644 src/content/docs/ja/4x/starter/static-files.mdx create mode 100644 src/content/docs/ja/5x/advanced/developing-template-engines.md create mode 100644 src/content/docs/ja/5x/guide/behind-proxies.mdx create mode 100644 src/content/docs/ja/5x/guide/debugging.mdx create mode 100644 src/content/docs/ja/5x/guide/error-handling.mdx create mode 100644 src/content/docs/ja/5x/guide/overriding-express-api.md create mode 100644 src/content/docs/ja/5x/guide/routing.mdx create mode 100644 src/content/docs/ja/5x/guide/using-middleware.mdx create mode 100644 src/content/docs/ja/5x/guide/using-template-engines.mdx create mode 100644 src/content/docs/ja/5x/guide/writing-middleware.mdx create mode 100644 src/content/docs/ja/5x/starter/basic-routing.mdx create mode 100644 src/content/docs/ja/5x/starter/examples.mdx create mode 100644 src/content/docs/ja/5x/starter/faq.md create mode 100644 src/content/docs/ja/5x/starter/generator.mdx create mode 100644 src/content/docs/ja/5x/starter/hello-world.mdx create mode 100644 src/content/docs/ja/5x/starter/installing.mdx create mode 100644 src/content/docs/ja/5x/starter/static-files.mdx create mode 100644 src/content/docs/ko/4x/advanced/developing-template-engines.md create mode 100644 src/content/docs/ko/4x/guide/behind-proxies.mdx create mode 100644 src/content/docs/ko/4x/guide/debugging.mdx create mode 100644 src/content/docs/ko/4x/guide/error-handling.mdx create mode 100644 src/content/docs/ko/4x/guide/overriding-express-api.md create mode 100644 src/content/docs/ko/4x/guide/routing.mdx create mode 100644 src/content/docs/ko/4x/guide/using-middleware.mdx create mode 100644 src/content/docs/ko/4x/guide/using-template-engines.mdx create mode 100644 src/content/docs/ko/4x/guide/writing-middleware.mdx create mode 100644 src/content/docs/ko/4x/starter/basic-routing.mdx create mode 100644 src/content/docs/ko/4x/starter/examples.mdx create mode 100644 src/content/docs/ko/4x/starter/faq.md create mode 100644 src/content/docs/ko/4x/starter/generator.mdx create mode 100644 src/content/docs/ko/4x/starter/hello-world.mdx create mode 100644 src/content/docs/ko/4x/starter/installing.mdx create mode 100644 src/content/docs/ko/4x/starter/static-files.mdx create mode 100644 src/content/docs/ko/5x/advanced/developing-template-engines.md create mode 100644 src/content/docs/ko/5x/guide/behind-proxies.mdx create mode 100644 src/content/docs/ko/5x/guide/debugging.mdx create mode 100644 src/content/docs/ko/5x/guide/error-handling.mdx create mode 100644 src/content/docs/ko/5x/guide/overriding-express-api.md create mode 100644 src/content/docs/ko/5x/guide/routing.mdx create mode 100644 src/content/docs/ko/5x/guide/using-middleware.mdx create mode 100644 src/content/docs/ko/5x/guide/using-template-engines.mdx create mode 100644 src/content/docs/ko/5x/guide/writing-middleware.mdx create mode 100644 src/content/docs/ko/5x/starter/basic-routing.mdx create mode 100644 src/content/docs/ko/5x/starter/examples.mdx create mode 100644 src/content/docs/ko/5x/starter/faq.md create mode 100644 src/content/docs/ko/5x/starter/generator.mdx create mode 100644 src/content/docs/ko/5x/starter/hello-world.mdx create mode 100644 src/content/docs/ko/5x/starter/installing.mdx create mode 100644 src/content/docs/ko/5x/starter/static-files.mdx create mode 100644 src/content/docs/pt-br/4x/advanced/developing-template-engines.md create mode 100644 src/content/docs/pt-br/4x/guide/behind-proxies.mdx create mode 100644 src/content/docs/pt-br/4x/guide/debugging.mdx create mode 100644 src/content/docs/pt-br/4x/guide/error-handling.mdx create mode 100644 src/content/docs/pt-br/4x/guide/overriding-express-api.md create mode 100644 src/content/docs/pt-br/4x/guide/routing.mdx create mode 100644 src/content/docs/pt-br/4x/guide/using-middleware.mdx create mode 100644 src/content/docs/pt-br/4x/guide/using-template-engines.mdx create mode 100644 src/content/docs/pt-br/4x/guide/writing-middleware.mdx create mode 100644 src/content/docs/pt-br/4x/starter/basic-routing.mdx create mode 100644 src/content/docs/pt-br/4x/starter/examples.mdx create mode 100644 src/content/docs/pt-br/4x/starter/faq.md create mode 100644 src/content/docs/pt-br/4x/starter/generator.mdx create mode 100644 src/content/docs/pt-br/4x/starter/hello-world.mdx create mode 100644 src/content/docs/pt-br/4x/starter/installing.mdx create mode 100644 src/content/docs/pt-br/4x/starter/static-files.mdx create mode 100644 src/content/docs/pt-br/5x/advanced/developing-template-engines.md create mode 100644 src/content/docs/pt-br/5x/guide/behind-proxies.mdx create mode 100644 src/content/docs/pt-br/5x/guide/debugging.mdx create mode 100644 src/content/docs/pt-br/5x/guide/error-handling.mdx create mode 100644 src/content/docs/pt-br/5x/guide/overriding-express-api.md create mode 100644 src/content/docs/pt-br/5x/guide/routing.mdx create mode 100644 src/content/docs/pt-br/5x/guide/using-middleware.mdx create mode 100644 src/content/docs/pt-br/5x/guide/using-template-engines.mdx create mode 100644 src/content/docs/pt-br/5x/guide/writing-middleware.mdx create mode 100644 src/content/docs/pt-br/5x/starter/basic-routing.mdx create mode 100644 src/content/docs/pt-br/5x/starter/examples.mdx create mode 100644 src/content/docs/pt-br/5x/starter/faq.md create mode 100644 src/content/docs/pt-br/5x/starter/generator.mdx create mode 100644 src/content/docs/pt-br/5x/starter/hello-world.mdx create mode 100644 src/content/docs/pt-br/5x/starter/installing.mdx create mode 100644 src/content/docs/pt-br/5x/starter/static-files.mdx create mode 100644 src/content/docs/zh-tw/4x/advanced/developing-template-engines.md create mode 100644 src/content/docs/zh-tw/4x/guide/behind-proxies.mdx create mode 100644 src/content/docs/zh-tw/4x/guide/debugging.mdx create mode 100644 src/content/docs/zh-tw/4x/guide/error-handling.mdx create mode 100644 src/content/docs/zh-tw/4x/guide/overriding-express-api.md create mode 100644 src/content/docs/zh-tw/4x/guide/routing.mdx create mode 100644 src/content/docs/zh-tw/4x/guide/using-middleware.mdx create mode 100644 src/content/docs/zh-tw/4x/guide/using-template-engines.mdx create mode 100644 src/content/docs/zh-tw/4x/guide/writing-middleware.mdx create mode 100644 src/content/docs/zh-tw/4x/starter/basic-routing.mdx create mode 100644 src/content/docs/zh-tw/4x/starter/examples.mdx create mode 100644 src/content/docs/zh-tw/4x/starter/faq.md create mode 100644 src/content/docs/zh-tw/4x/starter/generator.mdx create mode 100644 src/content/docs/zh-tw/4x/starter/hello-world.mdx create mode 100644 src/content/docs/zh-tw/4x/starter/installing.mdx create mode 100644 src/content/docs/zh-tw/4x/starter/static-files.mdx create mode 100644 src/content/docs/zh-tw/5x/advanced/developing-template-engines.md create mode 100644 src/content/docs/zh-tw/5x/guide/behind-proxies.mdx create mode 100644 src/content/docs/zh-tw/5x/guide/debugging.mdx create mode 100644 src/content/docs/zh-tw/5x/guide/error-handling.mdx create mode 100644 src/content/docs/zh-tw/5x/guide/overriding-express-api.md create mode 100644 src/content/docs/zh-tw/5x/guide/routing.mdx create mode 100644 src/content/docs/zh-tw/5x/guide/using-middleware.mdx create mode 100644 src/content/docs/zh-tw/5x/guide/using-template-engines.mdx create mode 100644 src/content/docs/zh-tw/5x/guide/writing-middleware.mdx create mode 100644 src/content/docs/zh-tw/5x/starter/basic-routing.mdx create mode 100644 src/content/docs/zh-tw/5x/starter/examples.mdx create mode 100644 src/content/docs/zh-tw/5x/starter/faq.md create mode 100644 src/content/docs/zh-tw/5x/starter/generator.mdx create mode 100644 src/content/docs/zh-tw/5x/starter/hello-world.mdx create mode 100644 src/content/docs/zh-tw/5x/starter/installing.mdx create mode 100644 src/content/docs/zh-tw/5x/starter/static-files.mdx create mode 100644 src/content/pages/de/advanced/best-practice-performance.md create mode 100644 src/content/pages/de/advanced/best-practice-security.mdx create mode 100644 src/content/pages/de/advanced/healthcheck-graceful-shutdown.md create mode 100644 src/content/pages/de/advanced/security-updates.mdx create mode 100644 src/content/pages/de/guide/database-integration.mdx create mode 100644 src/content/pages/de/guide/migrating-4.mdx create mode 100644 src/content/pages/de/guide/migrating-5.mdx create mode 100644 src/content/pages/de/resources/glossary.mdx create mode 100644 src/content/pages/de/resources/utils.md create mode 100644 src/content/pages/de/support.md create mode 100644 src/content/pages/es/advanced/best-practice-performance.md create mode 100644 src/content/pages/es/advanced/best-practice-security.mdx create mode 100644 src/content/pages/es/advanced/healthcheck-graceful-shutdown.md create mode 100644 src/content/pages/es/advanced/security-updates.mdx create mode 100644 src/content/pages/es/guide/database-integration.mdx create mode 100644 src/content/pages/es/guide/migrating-4.mdx create mode 100644 src/content/pages/es/guide/migrating-5.mdx create mode 100644 src/content/pages/es/resources/glossary.mdx create mode 100644 src/content/pages/es/resources/utils.md create mode 100644 src/content/pages/es/support.md create mode 100644 src/content/pages/fr/advanced/best-practice-performance.md create mode 100644 src/content/pages/fr/advanced/best-practice-security.mdx create mode 100644 src/content/pages/fr/advanced/healthcheck-graceful-shutdown.md create mode 100644 src/content/pages/fr/advanced/security-updates.mdx create mode 100644 src/content/pages/fr/guide/database-integration.mdx create mode 100644 src/content/pages/fr/guide/migrating-4.mdx create mode 100644 src/content/pages/fr/guide/migrating-5.mdx create mode 100644 src/content/pages/fr/resources/glossary.mdx create mode 100644 src/content/pages/fr/resources/utils.md create mode 100644 src/content/pages/fr/support.md create mode 100644 src/content/pages/it/advanced/best-practice-performance.md create mode 100644 src/content/pages/it/advanced/best-practice-security.mdx create mode 100644 src/content/pages/it/advanced/healthcheck-graceful-shutdown.md create mode 100644 src/content/pages/it/advanced/security-updates.mdx create mode 100644 src/content/pages/it/guide/database-integration.mdx create mode 100644 src/content/pages/it/guide/migrating-4.mdx create mode 100644 src/content/pages/it/guide/migrating-5.mdx create mode 100644 src/content/pages/it/resources/glossary.mdx create mode 100644 src/content/pages/it/resources/utils.md create mode 100644 src/content/pages/it/support.md create mode 100644 src/content/pages/ja/advanced/best-practice-performance.md create mode 100644 src/content/pages/ja/advanced/best-practice-security.mdx create mode 100644 src/content/pages/ja/advanced/healthcheck-graceful-shutdown.md create mode 100644 src/content/pages/ja/advanced/security-updates.mdx create mode 100644 src/content/pages/ja/guide/database-integration.mdx create mode 100644 src/content/pages/ja/guide/migrating-4.mdx create mode 100644 src/content/pages/ja/guide/migrating-5.mdx create mode 100644 src/content/pages/ja/resources/glossary.mdx create mode 100644 src/content/pages/ja/resources/utils.md create mode 100644 src/content/pages/ja/support.md create mode 100644 src/content/pages/ko/advanced/best-practice-performance.md create mode 100644 src/content/pages/ko/advanced/best-practice-security.mdx create mode 100644 src/content/pages/ko/advanced/healthcheck-graceful-shutdown.md create mode 100644 src/content/pages/ko/advanced/security-updates.mdx create mode 100644 src/content/pages/ko/guide/database-integration.mdx create mode 100644 src/content/pages/ko/guide/migrating-4.mdx create mode 100644 src/content/pages/ko/guide/migrating-5.mdx create mode 100644 src/content/pages/ko/resources/glossary.mdx create mode 100644 src/content/pages/ko/resources/utils.md create mode 100644 src/content/pages/ko/support.md create mode 100644 src/content/pages/pt-br/advanced/best-practice-performance.md create mode 100644 src/content/pages/pt-br/advanced/best-practice-security.mdx create mode 100644 src/content/pages/pt-br/advanced/healthcheck-graceful-shutdown.md create mode 100644 src/content/pages/pt-br/advanced/security-updates.mdx create mode 100644 src/content/pages/pt-br/guide/database-integration.mdx create mode 100644 src/content/pages/pt-br/guide/migrating-4.mdx create mode 100644 src/content/pages/pt-br/guide/migrating-5.mdx create mode 100644 src/content/pages/pt-br/resources/glossary.mdx create mode 100644 src/content/pages/pt-br/resources/utils.md create mode 100644 src/content/pages/pt-br/support.md create mode 100644 src/content/pages/zh-tw/advanced/best-practice-performance.md create mode 100644 src/content/pages/zh-tw/advanced/best-practice-security.mdx create mode 100644 src/content/pages/zh-tw/advanced/healthcheck-graceful-shutdown.md create mode 100644 src/content/pages/zh-tw/advanced/security-updates.mdx create mode 100644 src/content/pages/zh-tw/guide/database-integration.mdx create mode 100644 src/content/pages/zh-tw/guide/migrating-4.mdx create mode 100644 src/content/pages/zh-tw/guide/migrating-5.mdx create mode 100644 src/content/pages/zh-tw/resources/glossary.mdx create mode 100644 src/content/pages/zh-tw/resources/utils.md create mode 100644 src/content/pages/zh-tw/support.md diff --git a/src/content/docs/de/4x/advanced/developing-template-engines.md b/src/content/docs/de/4x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..243960da6a --- /dev/null +++ b/src/content/docs/de/4x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Template-Engines für Express entwickeln +description: Erfahren Sie, wie Sie mithilfe von app.engine() benutzerdefinierte Template-Engines für Express.js entwickeln können, mit Beispielen zur Erstellung und Integration Ihrer eigenen Template-Rendering-Logik. +--- + +Benutze die `app.engine(ext, callback)` Methode, um deine eigene Template-Engine zu erstellen. `ext` bezieht sich auf die Dateierweiterung, und `callback` ist die Template-Engine-Funktion, , die die folgenden Elemente als Parameter akzeptiert: den Speicherort der Datei, das Optionsobjekt und die Callback-Funktion. + +Der folgende Code ist ein Beispiel für die Implementierung einer sehr einfachen Template-Engine zum Rendern von `.ntl` Dateien. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +Deine App wird nun in der Lage sein, `.ntl`-Dateien zu rendern. Erstelle eine Datei namens `index.ntl` im `views` Verzeichnis mit folgendem Inhalt. + +```pug +#title# +#message# +``` + +Erstellen Sie dann die folgende Route in Ihrer App. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +Wenn du eine Anfrage an die Startseite stellt, wird `index.ntl` als HTML dargestellt. diff --git a/src/content/docs/de/4x/guide/behind-proxies.mdx b/src/content/docs/de/4x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..786e7aff5f --- /dev/null +++ b/src/content/docs/de/4x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Express hinter Proxies +description: Lernen Sie, wie Sie Express.js Anwendungen so konfigurieren, dass sie hinter Reverse Proxies korrekt arbeiten, einschließlich der Trust-Proxy-Einstellung für Client-IP-Adressen. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Wenn Sie eine Express-App hinter einem Reverse Proxy ausführen, können einige der Express-APIs andere Werte als erwartet zurückgeben. Um dies anzupassen die Einstellung `trust proxy` kann verwendet werden, um Informationen auszublenden, die vom Reverse Proxy in den Express API bereitgestellt werden. Das häufigste Problem sind Express-APIs, die die IP-Adresse des Clients offenlegen, statt dessen eine interne IP-Adresse des Reverse Proxy anzeigen. + + + +Bei der Konfiguration der `trust proxy` Einstellung ist es wichtig, das genaue Setup des +Reverse Proxy zu verstehen. Da diese Einstellung den in der Anfrage angegebenen Werten vertrauen wird Es ist wichtig, dass +die Kombination der Einstellung in Express mit der Funktionsweise des Reverse Proxy übereinstimmt. + + + +Die Anwendungseinstellung `trust proxy` kann auf einen der in der folgenden Tabelle aufgelisteten Werte gesetzt werden. + + + + + + + + + + + + + + + + + + + + + +
TypWert
Boolean +Wenn `true`, wird die IP-Adresse des Clients als linker Eintrag im `X-Forwarded-For` Header verstanden. + +Falls „falsch“ die App als direkt gegenüber dem Client verstanden wird und die IP-Adresse des Clients von „req.socket.remoteAddress“ abgeleitet wird. Dies ist die Standardeinstellung. + + +Wenn Sie auf `true` setzen, ist es wichtig sicherzustellen, dass der letzte Reverse Proxy alle folgenden HTTP-Header löscht/überschreibt: `X-Forwarded-For`, `X-Forwarded-Host` und `X-Forwarded-Proto`, andernfalls ist es möglich, dass der Client irgendeinen Wert angibt. + +
IP-Adressen +Eine IP-Adresse, ein Subnetz oder ein Array von IP-Adressen und Subnetzen, die darauf vertrauen, dass es sich um einen Reverse Proxy handelt. Die folgende Liste zeigt die vorkonfigurierten Subnetznamen an: + +* loopback - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +Sie können IP-Adressen auf jede der folgenden Arten festlegen: + +```js +app.set('trust proxy', 'loopback'); // ein einzelnes Subnetz +app.set('trust proxy', 'loopback, 123.123.123.123''); // ein Subnetz und eine Adresse +angeben. et('trust proxy', 'loopback, linklocal, uniquelocal'); // mehrere Subnetze als CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // mehrere Subnetze als Array angeben +``` + +Wenn angegeben, werden die IP-Adressen oder Subnetze vom Prozess der Adressermittlung ausgeschlossen und die dem Anwendungsserver nächstgelegene nicht vertrauenswürdige IP-Adresse wird als IP-Adresse des Clients ermittelt. Dies funktioniert indem überprüft wird, ob `req.socket.remoteAddress` vertrauenswürdig ist. Wenn ja, dann wird jede Adresse in `X-Forwarded-For` von rechts nach links bis zur ersten Adresse überprüft, die nicht vertrauenswürdig ist. + +
Nummer +Benutzen Sie die Adresse, die höchstens `n` von der Express-Anwendung entfernt ist. `req.socket.remoteAddress` ist der erste Hop, und der Rest wird im `X-Forwarded-For` Header von rechts nach links gesucht. Ein Wert von `0` bedeutet, dass die erste nicht vertrauenswürdige Adresse `req.socket.remoteAddress` ist, d.h. es gibt keinen Reverse-Proxy. + + +Bei der Verwendung dieser Einstellung ist es wichtig sicherzustellen, dass es keine Multiple gibt, verschiedene Pfade zur Express-Anwendung, so dass der Client kleiner sein kann als die konfigurierte Anzahl von Hops, die entfernt sind andernfalls kann es möglich sein, dass der Kunde irgendeinen Wert angibt. + +
Funktion +Benutzerdefinierte Vertrauens-Implementierung. + +```js +app.set('trust proxy', (ip) => { + if (ip === '127.0.0.1' || ip === '123.123.123. 23') + return true; // vertrauenswürdige IPs + else return false; +}); +``` + +
+ +Das Aktivieren von `trust proxy` hat folgende Auswirkungen: + + + +Die `trust proxy` Einstellung ist mit dem [proxy-addr](https://www.npmjs.com/package/proxy-addr) Paket implementiert. Weitere Informationen finden Sie in der Dokumentation. diff --git a/src/content/docs/de/4x/guide/debugging.mdx b/src/content/docs/de/4x/guide/debugging.mdx new file mode 100644 index 0000000000..44802397e8 --- /dev/null +++ b/src/content/docs/de/4x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Debuggen Express +description: Erfahren Sie, wie Sie Debugging-Logs in Express.js-Anwendungen aktivieren und nutzen können, indem Sie die DEBUG-Umgebungsvariable für verbesserte Fehlerbehebung setzen. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Um alle internen Logs zu sehen, die in Express verwendet werden, setzen Sie die Umgebungsvariable `DEBUG` auf +`express:*` beim Starten Ihrer App. + +```bash +$ DEBUG=Express:* node index.js +``` + +Verwenden Sie unter Windows den entsprechenden Befehl. + +```bash +> $env:DEBUG = "Express:*"; node index.js +``` + +Das Ausführen dieses Befehls auf der vom [Express-Generator] generierten Standard-App (/en/starter/generator) gibt folgende Ausgabe aus: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +Wenn eine Anfrage an die App gestellt wird, sehen Sie die im Express-Code angegebenen Protokolle: + +```bash + express :router dispatching GET / +4h + express :router query : / +2ms + express :router expresInit : / +0ms + express:router favicon : / +0ms + express :router logger : / +1ms + express :router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express :router cookieParser : / +0ms + express:router stylus : / +0ms + express :router serveStatic : / +2ms + express :router router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index. ug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +Um die Protokolle nur von der Router-Implementierung zu sehen, setzen Sie den Wert `DEBUG` auf `express:router`. Um Protokolle nur von der Anwendungsimplementierung zu sehen, setzten Sie den Wert von `DEBUG` auf `express:application`, und so weiter. + +## Anwendungen generiert von `Express` + +Eine Anwendung, die durch den Befehl `express generiert` erzeugt wird, benutzt das Modul `debug` und sein Debug-Namensraum wird auf den Namen der Anwendung übertragen. + +Wenn Sie zum Beispiel die App mit `$ express Beispiel-App` erstellt haben, können Sie die Debug-Anweisungen mit folgendem Befehl aktivieren: + +```bash +$ DEBUG=Beispiel-app:* Knoten ./bin/www +``` + +Sie können mehr als einen Debug-Namensraum angeben, indem Sie eine kommaseparierte Namensliste zuweisen: + +```bash +$ DEBUG=http,mail,Express:* node index.js +``` + +## Erweiterte Optionen + +Wenn Sie über Node.js laufen, können Sie ein paar Umgebungsvariablen festlegen, die das Verhalten der Debug-Protokollierung ändern: + +| Name | Zweck | +| ------------------- | --------------------------------------------------------------------------- | +| `DEBUG` | Aktiviere/deaktiviert bestimmte Debugging-Namensräume. | +| DEBUG_COLORS | Gibt an, ob Farben in der Debug-Ausgabe verwendet werden sollen oder nicht. | +| DEBUG_DEPTH\` | Objektüberprüfungstiefe. | +| `DEBUG_FD` | Datei-Deskriptor, in den die Debug-Ausgabe geschrieben wird. | +| `DEBUG_SHOW_HIDDEN` | Zeigt versteckte Eigenschaften auf untersuchten Objekten. | + + + +Die Umgebungsvariablen, die mit `DEBUG_` beginnen, werden am Ende in ein Optionsobjekt +konvertiert, das mit `%o`/`%O` Formate verwendet wird. Siehe die Dokumentation von Node.js für +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) für die vollständige +Liste. + + diff --git a/src/content/docs/de/4x/guide/error-handling.mdx b/src/content/docs/de/4x/guide/error-handling.mdx new file mode 100644 index 0000000000..d3d51364b4 --- /dev/null +++ b/src/content/docs/de/4x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Fehler beim Umgang +description: Verstehen Sie, wie Express.js Fehler im synchronen und asynchronen Code behandelt, und lernen Sie, benutzerdefinierte Fehlerbehandlung Middleware für Ihre Anwendungen zu implementieren. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Error Handling* bezieht sich darauf, wie Express Fehler fängt und verarbeitet, die +sowohl synchron als auch asynchron auftritt. Express kommt mit einem Standardfehler +\-Handler, damit Sie nicht Ihren eigenen schreiben müssen, um loszulegen. + +## Fehler beim Fangen + +Es ist wichtig sicherzustellen, dass Express alle Fehler, die auftreten, während +Routen-Handler und Middleware ausführt. + +Fehler, die im synchronen Code innerhalb von Routenhandlern und Middleware +auftreten, erfordern keine zusätzliche Arbeit. If synchronous code throws an error, then Express will +catch and process it. Zum Beispiel: + +```js +app.get('/', (req, res) => { + werfen neue Fehler ('BROKEN'); // Express fängt dies auf eigene Faust. +}); +``` + +For errors returned from asynchronous functions invoked by route handlers +and middleware, you must pass them to the `next()` function, where Express will +catch and process them. Zum Beispiel: + +```js +app.get('/', (req, res, next) => { + fs. eadFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Fehler an Express übergeben. + } else { + res. end(data); + } + }); +}); +``` + +Starting with Express 5, route handlers and middleware that return a Promise +will call `next(value)` automatically when they reject or throw an error. +Zum Beispiel: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = wait getUserById(req.params.id); + res.send(user); +}); +``` + +Wenn `getUserById` einen Fehler oder eine Ablehnung, wird `next` entweder mit +dem Wurffehler oder dem abgelehnten Wert aufgerufen. Wenn kein abgelehnter Wert angegeben wird, wird `next` +mit einem Standard-Fehlerobjekt aufgerufen, das vom Express-Router bereitgestellt wird. + +Wenn du etwas an die `next()` Funktion übergibt (außer den String `'route'`), +Express betrachtet die aktuelle Anfrage als Fehler und überspringt alle +verbleibenden Funktionen zur Fehlerbehandlung und Middleware. + +Wenn der Rückruf in einer Sequenz keine Daten enthält, nur Fehler, kannst du den Code +wie folgt vereinfachen: + +```js +app.get('/', [ + Funktion (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +Im obigen Beispiel wird `next` als Callback für `fs.writeFile` bereitgestellt, +, das mit oder ohne Fehler aufgerufen wird. Wenn kein Fehler vorliegt, wird der zweite +\-Handler ausgeführt, sonst fängt und verarbeitet Express den Fehler. + +Sie müssen Fehler, die im asynchronen Code auftreten, der von Routenhandlern oder +Middleware aufgerufen wird, auffangen und an Express zur Verarbeitung weiterleiten. Zum Beispiel: + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + next(err); + } + }, 100); +}); +``` + +Das obige Beispiel benutzt einen "try...catch"-Baustein, um Fehler im +asynchronen Code zu fangen und sie an den Express zu übergeben. Wenn der Block `try...catch` +weggelassen wurde, würde Express den Fehler nicht auffinden, da er nicht Teil des synchronen +Handlercodes ist. + +Verwende Versprechungen, um den Overhead des `try...catch`-Bausteins zu vermeiden oder wenn du Funktionen +benutzt, die Versprechen zurückgeben. Zum Beispiel: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + . hen(() => { + werfen neue Fehler ('BROKEN'); + }) + . atch(next); // Fehler werden an Express übergeben. +}); +``` + +Da Versprechungen automatisch sowohl synchrone Fehler als auch abgelehnte Versprechungen fangen, +du kannst einfach `next` angeben, da der letzte Catch Handler und Express Fehler fängt an +weil der Catch-Handler den Fehler als erstes Argument angibt. + +Sie können auch eine Kette von Handlern verwenden, um sich auf synchrone Fehler +zu stützen, indem Sie den asynchronen Code auf etwas Triviales reduzieren. Zum Beispiel: + +```js +app.get('/', [ + Funktion (req, res, next) { + fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals. ata = Daten; + next(err); + }); + }, + function (req, res) { + res. ocals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +Das obige Beispiel hat ein paar triviale Anweisungen aus dem Aufruf `readFile` +. If `readFile` causes an error, then it passes the error to Express, otherwise you +quickly return to the world of synchronous error handling in the next handler +in the chain. Dann versucht das obige Beispiel die Daten zu verarbeiten. Wenn dies fehlschlägt, fängt der Synchron-Fehlerhandler +ihn ab. Hätten Sie diese Verarbeitung innerhalb von +mit dem `readFile` Callback durchgeführt, dann könnte sich die Anwendung beenden und die Express-Fehler +Handler würden nicht laufen. + +Welche Methode Sie auch immer verwenden, wenn Sie wollen, dass Express-Fehlerbehandler aufgerufen werden und die +\-Anwendung überleben soll, Sie müssen sicherstellen, dass Express den Fehler empfängt. + +## Der Standard-Fehlerhandler + +Express kommt mit einem integrierten Fehlerbehandler, der sich um Fehler kümmert, die in der App auftreten könnten. Diese Standard-Middleware-Funktion wird am Ende des Middleware-Funktionstacks hinzugefügt. + +Wenn du einen Fehler an `next()` übergibt und ihn nicht in einem benutzerdefinierten +Handler behandelst, es wird vom eingebauten Fehlerhandler behandelt; wird der Fehler +mit der Stack-Spur an den Client geschrieben. The stack trace is not included +in the production environment. + + + +Setze die Umgebungsvariable `NODE_ENV` auf `production`, um die App im Produktionsmodus auszuführen. + + + +Wenn ein Fehler geschrieben wird, werden folgende Informationen zur Antwort +hinzugefügt: + +* Der `res.statusCode` wurde von `err.status` (oder `err.statusCode`) gesetzt. Wenn + sich dieser Wert außerhalb des 4xx oder 5xx Bereichs befindet, wird er auf 500 gesetzt. +* Die `res.statusMessage` wurde gemäß dem Statuscode gesetzt. +* Der Körper wird der HTML-Code der Statuscode-Nachricht sein, wenn in der Produktion + \-Umgebung, andernfalls 'err.stack' ist. +* Alle in einem `err.headers` Objekt angegebenen Header. + +Wenn du `next()` mit einem Fehler aufruft, nachdem du die +Antwort geschrieben hast (z. B. wenn beim Streamen der +Antwort auf den Client ein Fehler aufgetreten ist), der Express-Standardfehlerhandler schließt die +Verbindung und schlägt die Anfrage fehl. + +Wenn Sie also eine benutzerdefinierte Fehlerbehandlung hinzufügen, müssen Sie den Standard-Express-Fehlerbehandler an +delegieren wenn die Kopfzeilen +bereits an den Client gesendet wurden: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Beachte, dass der Standard-Fehlerhandler ausgelöst werden kann, wenn du `next()` mit einem Fehler +in deinem Code mehrmals aufrufst, auch wenn benutzerdefinierte Fehler beim Umgang mit Middleware vorhanden sind. + +Andere Fehler beim Umgang mit Middleware finden Sie unter [Express Middleware](/en/resources/middleware). + +## Schreibfehler + +Definieren Sie die Middleware-Funktionen wie andere Middleware-Funktionen +außer Funktionen zur Fehlerbehandlung haben vier Argumente anstelle von drei: +`(err, req, res, next)`. Zum Beispiel: + +```js +app.use(((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Etwas kaputt!'); +}); +``` + +Du definierst die Middleware zuletzt nach anderen `app.use()` und Routet Anrufe; zum Beispiel: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser. rlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app. se(methodOverride()); +app.use((err, req, res, next) => { + // Logik +}); +``` + +Antworten innerhalb einer Middleware-Funktion können in jedem Format sein, wie z.B. in einer HTML-Fehlerseite, einer einfachen Nachricht oder einem JSON-String. + +Für organisatorische (und höherstufige Framework) Zwecke können Sie +verschiedene Middleware-Funktionen definieren, so wie Sie es mit den regulären Middleware-Funktionen +würden. Zum Beispiel, um einen Fehlerhandler +für Anfragen mit `XHR` und denen ohne folgende zu definieren: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app. se( + bodyParser.urlencoded({ + extended: true, + }) +); +app. se(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +In diesem Beispiel könnten die generischen `logErrors` Anfrage und +Fehlerinformationen in `stderr` schreiben, zum Beispiel: + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +Auch in diesem Beispiel wird `clientErrorHandler` wie folgt definiert; in diesem Fall wird der Fehler explizit an den nächsten weitergegeben. + +Beachten Sie, dass, wenn *not* in einer Fehlerbehandlungsfunktion "Weiter" aufruft, Sie dafür verantwortlich sind, die Antwort zu schreiben (und zu beenden). Andernfalls werden diese Anträge "hängen" und sind nicht für die Müllsammlung berechtigt. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500). end({ error: 'Something failed!' }); + } else { + next(err); + } +} +``` + +Implementierung der "catch-all" `errorHandler` Funktion wie folgt (zum Beispiel): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +Wenn du einen Route-Handler mit mehreren Callback-Funktionen hast, kannst du den Parameter `route` verwenden, um zum nächsten Route-Handler zu springen. Zum Beispiel: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user. asPaid) { + // weitere Bearbeitung dieser Anfrage + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent. ind((err, doc) => { + if (err) return next(err); + res. son(doc); + }); + } +); +``` + +In diesem Beispiel wird der `getPaidContent` Handler übersprungen, aber alle verbleibenden Handler in `app` für `/a_route_behind_paywall` würden weiterhin ausgeführt werden. + + + +Aufrufe in `next()` und `next(err)` zeigen an, dass der aktuelle Handler abgeschlossen ist und in welchem Zustand ist. +`next(err)` überspringt alle verbleibenden Handler in der Kette mit Ausnahme derjenigen, die bis zu +eingerichtet sind, um Fehler wie oben beschrieben zu handhaben. + + diff --git a/src/content/docs/de/4x/guide/overriding-express-api.md b/src/content/docs/de/4x/guide/overriding-express-api.md new file mode 100644 index 0000000000..e7f6044eb7 --- /dev/null +++ b/src/content/docs/de/4x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Überschreiben der Express-API +description: Erfahren Sie, wie Sie die Express.js API anpassen und erweitern können, indem Sie Methoden und Eigenschaften der Request- und Response-Objekte mittels Prototypen überschreiben. +--- + +Die Express API besteht aus verschiedenen Methoden und Eigenschaften auf den Anfrage- und Antwort-Objekten. Diese werden vom Prototyp geerbt. Es gibt zwei Erweiterungspunkte für die Express API: + +1. Die globalen Prototypen unter `express.request` und `express.response`. +2. App-spezifische Prototypen bei `app.request` und `app.response`. + +Das Ändern der globalen Prototypen wirkt sich auf alle geladenen Express-Apps im selben Prozess aus. Wenn gewünscht, können Änderungen app-spezifisch gemacht werden, indem nur app-spezifische Prototypen nach dem Erstellen einer neuen App geändert werden. + +## Methoden + +Sie können die Signatur und das Verhalten bestehender Methoden mit eigenen überschreiben, indem Sie eine benutzerdefinierte Funktion zuweisen. + +Folgendes ist ein Beispiel für das Überschreiben des Verhaltens von [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +Die obige Implementierung ändert die ursprüngliche Signatur von `res.sendStatus`. Es akzeptiert nun einen Statuscode, Kodierungstyp und die Nachricht, die an den Client gesendet werden soll. + +Die überschriebene Methode kann nun auf diese Weise verwendet werden: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## Eigenschaften + +Eigenschaften in der Express-API sind entweder: + +1. Zugewiesene Eigenschaften (z.B. `req.baseUrl`, `req.originalUrl`) +2. Definiert als Getters (z. B.: `req.secure`, `req.ip`) + +Da Eigenschaften in Kategorie 1 dynamisch auf den `request` und `response` Objekten im Kontext des aktuellen Request-Antwort-Zyklus zugewiesen werden ihr Verhalten kann nicht überschrieben werden. + +Eigenschaften der Kategorie 2 können mit der Express API Extensions API überschrieben werden. + +Der folgende Code schreibt neu wie der Wert von `req.ip` abgeleitet wird. Jetzt gibt es einfach den Wert des `Client-IP` Request-Headers zurück. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Prototyp + +Um die Express API zur Verfügung zu stellen, werden die Anfrage/Antwort-Objekte an Express weitergegeben (via `app(req, res)`, zum Beispiel, müssen von der gleichen Prototypenkette zu erben. Standardmäßig ist dies `http.IncomingRequest.prototype` für die Anfrage und `http.ServerResponse.prototype` für die Antwort. + +Wenn nötig, wird empfohlen, dass dies nur auf der Anwendungsebene und nicht auf globaler Ebene geschieht. Achten Sie auch darauf, dass der verwendete Prototyp die Funktionalität so nah wie möglich an die Standard-Prototypen anpasst. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/de/4x/guide/routing.mdx b/src/content/docs/de/4x/guide/routing.mdx new file mode 100644 index 0000000000..709b3db818 --- /dev/null +++ b/src/content/docs/de/4x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Routing +description: Lernen Sie, wie Sie Routen in Express.js Anwendungen definieren und nutzen können, einschließlich Routenmethoden, Routenpfaden, Parameter und Router für modulare Route. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* bezieht sich darauf, wie die Endpunkte einer Anwendung (URIs) auf Kundenanfragen reagieren. +Für eine Einführung in das Routing siehe [Basic routing](/en/starter/basic-routing). + +Du definierst Routing, indem du Methoden des Express `app` Objekts verwendest, die den HTTP-Methoden entsprechen; +zum Beispiel, `app. et()` um GET-Anfragen und `app.post` zu behandeln, um POST-Anfragen zu bearbeiten. Für eine vollständige Liste +siehe [app.METHOD](/en/5x/api#app.METHOD). Du kannst auch [app.all()](/en/5x/api#app.all) verwenden, um alle HTTP-Methoden und [app. se()](/en/5x/api#app.use) bis +Middleware als Callback-Funktion angeben (siehe [Middleware](/en/guide/using-middleware) für Details). + +Diese Routing-Methoden geben eine Callback-Funktion (manchmal auch "handler functions") an, die aufgerufen wird, wenn die Anwendung eine Anfrage an die angegebene Route (Endpunkt) und die HTTP-Methode erhält. Mit anderen Worten, die Anwendung "lauscht" für Anforderungen, die mit der angegebenen Route(s) und Methode(n) übereinstimmen und wenn es ein Spiel erkennt, ruft es die angegebene Callback-Funktion auf. + +In der Tat können die Routing-Methoden mehr als eine Callback-Funktion als Argumente haben. +Mit mehreren Callback-Funktionen, es ist wichtig, `next` als Argument für die Callback-Funktion zur Verfügung zu stellen und dann `next()` im Körper der Funktion aufzurufen, um die Steuerung +an den nächsten Callback zu übergeben. + +Der folgende Code ist ein Beispiel für eine sehr einfache Route. + +```js +const express = require('express '); +const app = express = ); + +// Mit "Hallo world" antworten, wenn eine GET-Anfrage an die Homepage +App gestellt wird. et('/', (req, res) => { + res.send('Hallo Welt'); +}); +``` + +## Routenmethoden + +Eine Route-Methode wird von einer der HTTP-Methoden abgeleitet und an eine Instanz der Klasse \`express angehängt. + +Der folgende Code ist ein Beispiel für Routen, die für die `GET` und die `POST` Methoden im Root der App definiert sind. + +```js +// GET Methode Route +app.get('/', (req, res) => { + res. end('GET request to the homepage'); +}); + +// POST method route +app. ost('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Express unterstützt Methoden, die allen HTTP-Anfragemethoden entsprechen: `get`, `post` und so weiter. +Für eine vollständige Liste siehe [app.METHOD](/en/5x/api#app.METHOD). + +Es gibt eine spezielle Routing-Methode, `app.all()`, die benutzt wird, um Middleware-Funktionen an einem Pfad für *all* HTTP-Requestmethoden zu laden. Zum Beispiel wird der folgende Handler für Anfragen an die Route `"/secret"` ausgeführt, ob `GET` verwendet wird, `POST`, `PUT`, `DELETE`, oder jede andere HTTP-Anfragemethode, die im [http module]unterstützt wird (https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Zugriff auf den geheimen Abschnitt ...'); + next(); // Kontrolle an den nächsten Handler +}); +``` + +## Routenpfade + +Routenpfade in Kombination mit einer Anfragemethode definieren die Endpunkte, an denen Anfragen gestellt werden können. Routenpfade können Zeichenketten, Zeichenkettenmuster oder reguläre Ausdrücke sein. + + + +Im Ausdruck 5, die Zeichen `? , `+`, `\*`, `[]`und`()\` werden anders behandelt als in Version +4, bitte lesen Sie die [Migrationsanleitung](/en/guide/migrating-5#path-syntax) für weitere Informationen. + + + + + +Im Ausdruck 4 müssen reguläre Ausdrücke wie `$` mit einem `\` maskiert werden. + + + + + +Express verwendet [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) um die Route +Pfade zu treffen; lesen Sie die Dokumentation zu regexp für alle Möglichkeiten bei der Definition von Routenpfaden. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) ist ein praktisches Werkzeug für +grundlegende Express-Routen zu testen, obwohl es kein Muster-Matching unterstützt. + + + +Abfragezeichenketten sind nicht Teil des Routenweges. + +### Routenpfade basierend auf Zeichenketten + +Dieser Routenpfad wird den Anfragen an die Root-Route `/` entsprechen. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +Dieser Routenpfad wird den Anfragen auf `/about` entsprechen. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +Dieser Routenpfad entspricht den Anfragen zu `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Routenpfade basierend auf Stringmustern + + + +Die Zeichenkettenmuster in Express 5 funktionieren nicht mehr. Weitere Informationen finden Sie in der Migration +Anleitung . + + + +Dieser Routenpfad stimmt mit `acd` und `abcd` überein. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +Dieser Routenpfad stimmt mit `abcd`, `abbcd`, `abbbcd` usw. überein. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +Dieser Routenpfad stimmt mit `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd` usw. überein. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +Dieser Routenpfad stimmt mit `/abe` und `/abcde` überein. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Routenpfade basierend auf regulären Ausdrücken + +Dieser Routenpfad stimmt mit einem "a" darin überein. + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +Dieser Routenpfad stimmt mit 'butterfly' und 'Drachenfly' überein, aber nicht mit 'butterflyman', 'Drachenflyman' und so weiter. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Routenparameter + +Routenparameter sind URL-Segmente, die zur Erfassung der an ihrer Position in der URL angegebenen Werte verwendet werden. Die erfassten Werte werden im Objekt `req.params` gefüllt, wobei der Name des im Pfad angegebenen Routenparameter als ihre jeweiligen Schlüssel angegeben ist. + +``` +Routenpfad: /users/:userId/books/:bookId +Anfrage-URL: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +Um Routen mit Routenparametern zu definieren, geben Sie einfach die Routenparameter im Pfad der Route, wie unten gezeigt, an. + +```js +app.get('/users/:userId/bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +Der Name der Routenparameter muss aus "Wortzeichen" ([A-Za-z0-9_] ) bestehen. + + + +Da die Bindestriche (`-`) und der Punkt (`.`) wörtlich interpretiert werden, können sie zusammen mit Routenparametern für nützliche Zwecke verwendet werden. + +``` +Routenpfad: /flights/:from-:to +Abfrage URL: http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Routenpfad: /plantae/:genus.:species +Anfrage URL: http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +In express 5, Regexp characters are not supported in route paths, for more information please +refer to the [migration guide](/en/guide/migrating-5#path-syntax). + + + +Um mehr Kontrolle über den exakten String zu haben, der mit einem Route-Parameter übereinstimmen kann, können Sie einen regulären Ausdruck in Klammern (`()`) anhängen: + +``` +Routenpfad: /user/:userId(\d+) +Anfrage-URL: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Weil der reguläre Ausdruck in der Regel Teil einer literalen Zeichenkette ist, Stellen Sie sicher, dass Sie `\` +Zeichen mit einem zusätzlichen Backslash maskieren, zum Beispiel `\d+`. + + + + +In Express 4.x wird das `*` Zeichen in regulären Ausdrücken nicht auf die übliche Weise interpretiert. Benutze `{0,}` anstelle von `*`. Dies wird wahrscheinlich in Express 5 behoben. + + +## Routenhandler + +Du kannst mehrere Callback-Funktionen bereitstellen, die sich wie [middleware](/en/guide/using-middleware) verhalten um eine Anfrage zu bearbeiten. Die einzige Ausnahme ist, dass diese Callbacks `next('route')` aufrufen könnten, um die restlichen Rufnummern zu umgehen. Sie können diesen Mechanismus nutzen, um Vorbedingungen auf einer Route aufzuerlegen, dann die Kontrolle an die nachfolgenden Routen übergeben, wenn es keinen Grund gibt, mit der aktuellen Route fortzufahren. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params. d === '0') { + return next('route'); + } + res. end(`User ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Special handler for user ID 0'); +}); +``` + +In diesem Beispiel: + +* `GET /user/5` → behandelt durch die erste Route → sendet "Benutzer 5" +* `GET /user/0` → erste Routenaufrufe `next('route')`, überspringt zur nächsten passenden `/user/:id` Route + +Routenhandler können in Form einer Funktion, eines Arrays von Funktionen oder Kombinationen beider sein, wie in den folgenden Beispielen gezeigt. + +Eine einzelne Callback-Funktion kann eine Route handhaben. Zum Beispiel: + +```js +app.get('/example/a', (req, res) => { + res.send('Hallo von A!'); +}); +``` + +Mehr als eine Callback-Funktion kann eine Route handhaben (stelle sicher, dass du das `next` Objekt angibst). Zum Beispiel: + +```js +app.get( + '/example/b', + (req, res, next) => { + Konsole. og('die Antwort wird von der nächsten Funktion gesendet. .'); + next(); + }, + (req, res) => { + res. end('Hallo von B!'); + } +); +``` + +Ein Array von Callback-Funktionen kann eine Route handhaben. Zum Beispiel: + +```js +const cb0 = function (req, res, next) { + Konsole. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +const cb2 = function (req, res) { + res. end('Hallo von C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +Eine Kombination aus unabhängigen Funktionen und Arrays von Funktionen kann eine Route handhaben. Zum Beispiel: + +```js +const cb0 = function (req, res, next) { + Konsole. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +App. et( + '/example/d', + [cb0, cb1], + (req, res, next) => { + Konsole. og('die Antwort wird von der nächsten Funktion gesendet. .'); + next(); + }, + (req, res) => { + res. end('Hallo von D!'); + } +); +``` + +## Antwortmethoden + +Die Methoden auf dem Antwortobjekt (`res`) in der folgenden Tabelle können eine Antwort an den Client senden und den Request-Antwort-Zyklus beenden. Wenn keine dieser Methoden von einem Routenhandler aufgerufen wird, bleibt die Client-Anfrage hängen. + +| Methode | Beschreibung | +| --------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | Fordern Sie eine Datei zum Download an. | +| [res.end()](/en/5x/api#res.end) | Beenden Sie den Antwort-Prozess. | +| [res.json()](/en/5x/api#res.json) | Sende eine JSON-Antwort. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Senden Sie eine JSON-Antwort mit JSONP-Unterstützung. | +| [res.redirect()](/en/5x/api#res.redirect) | Anfrage umleiten. | +| [res.render()](/en/5x/api#res.render) | Ansichtsvorlage ausblenden. | +| [res.send()](/en/5x/api#res.send) | Senden Sie eine Antwort von verschiedenen Typen. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Senden Sie eine Datei als octet-Stream. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Legen Sie den Antwort-Statuscode fest und senden Sie seine Zeichenfolge Repräsentation als Antwortkörper. | + +## app.route() + +Sie können verkettende Routenhandler für einen Routenpfad erstellen, indem Sie `app.route()` verwenden. +Da der Weg an einem einzigen Ort angegeben wird, ist die Schaffung modularer Routen hilfreich, ebenso wie die Reduzierung von Redundanz und Typos. Weitere Informationen über Routen finden Sie unter [Router() documentation](/en/5x/api#router). + +Hier ist ein Beispiel für verkettete Routenhandler, die mit `app.route()` definiert werden. + +```js +app + .route('/book') + .get((req, res) => { + res. end('Holt ein zufälliges Buch'); + }) + . ost(req, res) => { + res.send('Add a book'); + }) + . ut((req, res) => { + res.send('Buch aktualisieren'); +}); +``` + +## express.Router + +Verwende die Klasse `express.Router`, um modulare mountbare Routenhandler zu erstellen. Eine `Router`-Instanz ist ein komplettes Middleware- und Routing-System; aus diesem Grund wird sie oft als "Mini-App" bezeichnet. + +Das folgende Beispiel erzeugt einen Router als Modul, lädt eine Middleware-Funktion darin definiert einige Routen und mountet das Router-Modul auf einem Pfad in der Hauptanwendung. + +Erstelle eine Router-Datei namens `birds.js` im App-Verzeichnis, mit folgendem Inhalt: + +```js +const express = require('express'); +const Router = express. outer(); + +// Middleware, die spezifisch für diesen Router +const timeLog = (req, res, next) => { + Konsole ist. og('Zeit: ', Date.now()); + next(); +}; +Router. se(timeLog); + +// die Startseite Route +router.get('/', (req, res) => { + res. end('Birds home page'); +}); +// die "about route +definieren. et('/about', (req, res) => { + res.send('Über Vögel'); +}); + +module.exports = router; +``` + +Laden Sie dann das Router-Modul in der App: + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', Vögel); +``` + +Die App wird nun in der Lage sein, Anfragen an `/birds` und `/birds/about` zu bearbeiten, aufrufen sowie die Middleware-Funktion `timeLog` aufrufen, die spezifisch für die Route ist. + +Aber wenn die übergeordnete Route `/birds` Pfadparameter hat, wird sie standardmäßig nicht von den Unterrouten aus erreichbar sein. Um es zugänglich zu machen, müssen Sie die Option "mergeParams" an den Router-Konstruktor [reference](/en/5x/api#app.use) übergeben. + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/de/4x/guide/using-middleware.mdx b/src/content/docs/de/4x/guide/using-middleware.mdx new file mode 100644 index 0000000000..667105556e --- /dev/null +++ b/src/content/docs/de/4x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Middleware verwenden +description: Lernen Sie, wie Sie Middleware in Express.js-Anwendungen verwenden, einschließlich Middleware auf Anwendungsebene und Routerebene, Fehlerbehandlung und Integration von Middleware. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express ist ein Routing- und Middleware-Webframework mit minimaler Funktionalität: Eine Express-Anwendung ist im Wesentlichen eine Reihe von Middleware-Funktionsaufrufen. + +*Middleware* Funktionen sind Funktionen, die Zugriff auf das [request object](/en/5x/api#req) (`req`), das [Antwort-Objekt](/en/5x/api#res) (`res`) und die nächste Middleware-Funktion im Request-Antwort-Zyklus der Anwendung. Die nächste Middleware-Funktion wird üblicherweise durch eine Variable namens `next` bezeichnet. + +Middleware-Funktionen können folgende Aufgaben ausführen: + +* Führe jeden Code aus. +* Änderungen an der Anfrage und den Antwort-Objekten vornehmen. +* Beende den Request-Antwort-Zyklus. +* Rufen Sie die nächste Middleware-Funktion im Stack auf. + +Wenn die aktuelle Middleware-Funktion den Request-Antwort-Zyklus nicht beendet, muss sie `next()` aufrufen, um die Kontrolle an die nächste Middleware-Funktion zu übergeben. Andernfalls bleibt die Anfrage hängen. + +Eine Express-Anwendung kann folgende Arten von Middleware verwenden: + +* [Middleware](#middleware.application) +* [Router-Level-Middleware](#middleware.router) +* [Error-handling middleware](#middleware.error-handling) +* [Integrierte Middleware](#middleware.built-in) +* [Middleware von Drittanbietern](#middleware.third-party) + +Sie können Middleware auf Anwendungsebene und Routerebene mit einem optionalen Mount-Pfad laden. +Sie können auch eine Reihe von Middleware-Funktionen zusammen laden, die einen Sub-Stack des Middleware-Systems an einem Mount-Punkt erzeugen. + +## Middleware auf Anwendungsebene + +Binde Middleware auf Anwendungsebene an eine Instanz des [app object](/en/5x/api#app) durch Verwendung der `app.use()` und `app. ETHOD()` Funktionen, wobei `METHOD` die HTTP-Methode der Anfrage ist, die die Middleware-Funktion in Kleinbuchstaben behandelt (wie GET, PUT, oder POST) + +Dieses Beispiel zeigt eine Middleware-Funktion ohne Mount-Pfad. Die Funktion wird jedes Mal ausgeführt, wenn die App eine Anfrage erhält. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +Dieses Beispiel zeigt eine Middleware-Funktion, die auf dem `/user/:id` Pfad eingehängt ist. Die Funktion wird für jede Art von +HTTP-Anfrage im `/user/:id` Pfad ausgeführt. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +Dieses Beispiel zeigt eine Route und deren Handler-Funktion (Middleware-System). Die Funktion bearbeitet GET-Anfragen an den Pfad `/user/:id`. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +Hier ist ein Beispiel für das Laden einer Reihe von Middleware-Funktionen an einem Mount-Punkt, mit einem Mount-Pfad. +Es illustriert einen Middleware-Unterstapel, der Anfrageinformationen für jede Art von HTTP-Anfrage in den Pfad `/user/:id` ausgibt. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + console. og('Request Type:', req.method); + next(); + } +); +``` + +Routenhandler ermöglichen es Ihnen, mehrere Routen für einen Pfad zu definieren. Das folgende Beispiel definiert zwei Routen für GET-Anfragen zum Pfad `/user/:id`. Die zweite Route wird keine Probleme verursachen, aber sie wird nie aufgerufen, weil die erste Route den Request-Antwort-Zyklus beendet. + +Dieses Beispiel zeigt einen Middleware-Sub-Stack an, der GET-Anfragen im `/user/:id`-Pfad behandelt. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req. arams.id); + next(); + }, + (req, res, next) => { + res. end('User Info'); + } +); + +// Handler für den /user/:id Pfad, der die Benutzer-ID +App ausgibt. et('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +Um die restlichen Middleware-Funktionen eines Routers Middleware-Stacks zu überspringen, rufen Sie `next('route')` auf, um die Kontrolle an die nächste Route zu übergeben. + + + +`next('route')` funktioniert nur in Middleware-Funktionen, die mit den Funktionen +`app.METHOD()` oder `router.METHOD()` geladen wurden. + + + +Dieses Beispiel zeigt einen Middleware-Sub-Stack an, der GET-Anfragen im `/user/:id`-Pfad behandelt. + +```js +app.get( + '/user/:id', + (req, res, Nächste) => { + // wenn die Benutzer-ID 0 ist springe zur nächsten Route + wenn (req. arams. d === '0') als nächstes ('route'); + // Andernfalls übergeben Sie die Steuerung an die nächste Middleware-Funktion in diesem Stack + else next(); + }, + (req, res, next) => { + // Senden Sie eine reguläre Antwort + res. end('regular'); + } +); + +// Handler für den /user/:id Pfad, der eine spezielle Antwort +App sendet. et('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +Middleware kann auch in einem Array für Wiederverwendbarkeit deklariert werden. + +Dieses Beispiel zeigt ein Array mit einem Middleware-Sub-Stack an, das GET-Anfragen im Pfad `/user/:id` behandelt + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req. riginalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Request Type:', req. ethod); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +App. et('/user/:id', logStuff, (req, res, next) => { + res.send('User Info'); +}); +``` + +## Middleware auf Routerebene + +Middleware auf Router-Ebene funktioniert wie Middleware auf Anwendungsebene, es sei denn, es ist an eine Instanz von `express.Router()` gebunden. + +```js +const router = express.Router(); +``` + +Laden Sie die Middleware router-level mittels der Funktionen `router.use()` und `router.METHOD()`. + +Der folgende Beispielcode repliziert das oben angezeigte Middleware-System für Middleware auf Anwendungsebene: + +```js +const express = require('express'); +const app = express(); +const router = express. Externe(); + +// eine Middleware-Funktion ohne Mount-Pfad. Dieser Code wird für jede Anfrage an den Router +ausgeführt. se(req, res, next) => { + console.log('Zeit:', Datum. ow()); + next(); +}); + +// Ein Middleware-Sub-Stack zeigt Anfrageinformationen für jede Art von HTTP-Anfrage an den /user/:id path +Router an. se( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + Konsole. og('Request Typ:', req. ethod); + next(); + } +); + +// ein Middleware-Sub-Stack, der GET-Anfragen an den /user/:id path +Router verarbeitet. et( + '/user/:id', + (req, res, Nächste) => { + // wenn die Benutzer-ID 0 ist springe zum nächsten Router + wenn (req. arams. d === '0') als nächstes ('route'); + // Andernfalls übergeben Sie die Kontrolle an die nächste Middleware-Funktion in diesem Stapel + else next(); + }, + (req, res, next) => { + // rendern Sie eine reguläre Seite + res. ender('regular'); + } +); + +// Handler für den /user/:id Pfad, der eine spezielle Seite +Router darstellt. et('/user/:id', (req, res, next) => { + Konsole. og(req.params.id); + res.render('special'); +}); + +// Router auf die App +app.use('/', Router); +``` + +To skip the rest of the router's middleware functions, call `next('router')` +to pass control back out of the router instance. + +Dieses Beispiel zeigt einen Middleware-Sub-Stack an, der GET-Anfragen im `/user/:id`-Pfad behandelt. + +```js +const express = require('express'); +const app = express(); +const router = express. Externe (); + +// Vorhersage des Routers mit Scheck und Kaution bei Bedarf +Router. se((req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router. et('/user/:id', (req, res) => { + res.send('hallo, user!'); +}); + +// den Router verwenden und 401 alles, was durch die +App fällt. se('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## Fehler beim Umgang mit Middleware + + + +Bei der Fehlerbehebung der Middleware werden immer *vier* Argumente verwendet. Sie müssen vier Argumente angeben, um +als Middleware-Funktion zu identifizieren. Selbst wenn du das `next` +Objekt nicht verwenden musst, musst du es angeben, um die Signatur zu pflegen. Andernfalls wird das `next` Objekt +als reguläre Middleware interpretiert und wird Fehler nicht bearbeiten. + + + +Definieren Sie die Middleware-Funktionen wie andere Middleware-Funktionen außer mit vier Argumenten anstelle von drei, speziell mit der Signatur `(err, req, res, next)`: + +```js +app.use(((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Etwas kaputt!'); +}); +``` + +Details über die Fehlerbehandlungsmittelsoftware finden Sie hier: [Fehlerbehandlung](/en/guide/error-handling). + +## Integrierte Middleware + +Ab Version 4.x ist Express nicht mehr abhängig von [Connect](https://github.com/senchalabs/connect). Die Middleware- +\-Funktionen, die zuvor mit Express integriert wurden, befinden sich nun in separaten Modulen; siehe [Liste der Middleware-Funktionen](https://github.com/senchalabs/connect#middleware). + +Express hat die folgenden integrierten Middleware-Funktionen: + +* [express.static](/en/5x/api#express.static) dient statischen Assets wie HTML-Dateien, Bilder und so weiter. +* [express.json](/en/5x/api#express.json) analysiert eingehende Anfragen mit JSON Payloads. **HINWEIS: Verfügbar mit Express 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) analysiert eingehende Anfragen mit URL-kodierten Payloads. **HINWEIS: Verfügbar mit Express 4.16.0+** + +## Drittanbieter-Middleware + +Verwenden Sie Middleware von Drittanbietern, um Funktionen zu Express-Apps hinzuzufügen. + +Installieren Sie das Modul Node.js für die erforderliche Funktionalität, laden Sie es dann in Ihrer App auf der Anwendungsebene oder auf der Routerebene. + +Das folgende Beispiel zeigt die Installation und das Laden der Cookie-Parsing-Middleware-Funktion "cookie-parser". + +```bash +$ npm Cookie-Parser installieren +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// cookie-parsing middleware +app.use(cookieParser()); +``` + +Für eine partielle Liste der Middleware-Funktionen von Drittanbietern, die häufig mit Express verwendet werden, siehe: [Middleware](../resources/middleware). diff --git a/src/content/docs/de/4x/guide/using-template-engines.mdx b/src/content/docs/de/4x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..8fddcf43be --- /dev/null +++ b/src/content/docs/de/4x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Template-Engines mit Express verwenden +description: Entdecken Sie, wie Sie Template-Engines wie Pug, Handlebars und EJS mit Express.js integrieren und nutzen können, um dynamische HTML-Seiten effizient zu machen. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Eine *template engine* ermöglicht es Ihnen, statische Template-Dateien in Ihrer Anwendung zu verwenden. Zur Laufzeit ersetzt die Template-Engine +Variablen in einer Template-Datei mit aktuellen Werten und verwandelt die Vorlage in eine HTML-Datei, die an den Client gesendet wird. +Dieser Ansatz erleichtert die Gestaltung einer HTML-Seite. + +Der [Express-Anwendungsgenerator](/en/starter/generator) verwendet [Pug](https://pugjs.org/api/getting-started.html) als Standardwert, aber es unterstützt auch [Handlebars](https://www.npmjs.com/package/handlebars), und [EJS](https://www.npmjs.com/package/ejs), unter anderem. + +Um Template-Dateien zu rendern, setzen Sie folgende [Anwendungs-Einstellungen-Eigenschaften](/en/4x/api#app.set), in der Standardeinstellung `app.js`, die vom Generator erstellt wurde: + +* `views`, das Verzeichnis, in dem sich die Template-Dateien befinden. Eg: `app.set('views', './views')`. + Dies ist standardmäßig im Verzeichnis `views` im Root-Verzeichnis der Anwendung. +* `view engine`, die zu verwendende Template-Engine. Um zum Beispiel die Mückenvorlagen-Engine zu verwenden: `app.set('view engine', 'pug')`. + +Installieren Sie dann das entsprechende Template Engine npm Paket; zum Beispiel um Pug: + +```bash +$ npm Installations-Pug --save +``` + + +Express-konforme Template-Engines wie MUG exportieren eine Funktion namens `__express(filePath, options, callback)`, +welche `res.render()` aufruft, um den Template-Code zu rendern. + +Einige Template-Engines folgen nicht dieser Konvention. Die [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +Bibliothek folgt dieser Konvention, indem sie alle populären Template-Engines von Node.js abbildet, und arbeitet daher nahtlos in Express. + + + +Nachdem die View Engine gesetzt ist, müssen Sie nicht die Engine angeben oder das Template Engine Modul in Ihrer App laden; +Express lädt das Modul intern, zum Beispiel: + +```js +app.set('view engine', 'pug'); +``` + +Erstelle dann eine Pug Template Datei namens `index.pug` im `views` Verzeichnis mit folgendem Inhalt: + +```pug +html + Kopf + title= title + Körper + h1= Nachricht +``` + +Erstelle eine Route um die `index.pug` Datei zu rendern. Wenn die `view engine` Eigenschaft nicht gesetzt ist, +musst du die Erweiterung der `view` Datei angeben. Andernfalls können Sie es auslassen. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hallo there!' }); +}); +``` + +Wenn du eine Anfrage an die Startseite stellt, wird die `index.pug` Datei als HTML dargestellt. + +Der View Engine-Cache speichert nicht den Inhalt der Templateausgabe, sondern nur die zugrunde liegende Vorlage selbst. Die Ansicht wird noch mit jeder Anfrage neu gerendert, auch wenn der Cache eingeschaltet ist. diff --git a/src/content/docs/de/4x/guide/writing-middleware.mdx b/src/content/docs/de/4x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..dd0cf8e493 --- /dev/null +++ b/src/content/docs/de/4x/guide/writing-middleware.mdx @@ -0,0 +1,239 @@ +--- +title: Schreibe Middleware für die Verwendung in Express-Apps +description: Erfahren Sie, wie Sie benutzerdefinierte Middleware-Funktionen für Express.js-Anwendungen schreiben, einschließlich Beispielen und Best Practices zur Verbesserung der Request- und Response-Behandlung. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Middleware* Funktionen sind Funktionen, die Zugriff auf das [request object](/en/5x/api#req) (`req`), die [Antwort-Objekt](/en/5x/api#res) (`res`) und die `next` Funktion im Request-Antwort-Zyklus der Anwendung. Die `next`-Funktion ist eine Funktion im Express-Router, der beim Aufruf die Middleware ausführt, die die aktuelle Middleware abfolgt. + +Middleware-Funktionen können folgende Aufgaben ausführen: + +* Führe jeden Code aus. +* Änderungen an der Anfrage und den Antwort-Objekten vornehmen. +* Beende den Request-Antwort-Zyklus. +* Rufen Sie die nächste Middleware im Stapel auf. + +Wenn die aktuelle Middleware-Funktion den Request-Antwort-Zyklus nicht beendet, muss sie `next()` aufrufen, um die Kontrolle an die nächste Middleware-Funktion zu übergeben. Andernfalls bleibt die Anfrage hängen. + +Die folgende Abbildung zeigt die Elemente eines Middleware-Funktionsaufrufs: + +
+ + + + + +
+Elemente eines Middleware Funktionsaufrufs + +
HTTP-Methode, für die die Middleware-Funktion gilt.
+ +
+ Pfad (Route), für den die Middleware-Funktion gilt. +
+ +
+ Die Middleware-Funktion. +
+ +
+ Callback-Argument an die Middleware-Funktion, genannt "Next" durch Konvention. +
+ +
+ HTTP Antwort Argument auf die Middleware-Funktion, genannt "res" von + Konvention. +
+ +
HTTP Request Argument an die Middleware-Funktion, genannt "req" von Konvention.
+
+
+ +Beginnend mit Express 5 ruft Middleware-Funktionen, die ein Versprechen zurückgeben, `next(value)` auf, wenn sie einen Fehler ablehnen oder werfen. `next` wird entweder mit dem abgelehnten Wert oder mit dem Wurffehler aufgerufen. + +## Beispiel + +Hier ist ein Beispiel für eine einfache "Hallo World"-Express-Anwendung. +Der Rest dieses Artikels definiert und fügt der Anwendung drei Middleware-Funktionen hinzu: +eine mit dem Namen `myLogger`, die eine einfache Logmeldung ausgibt, einen namens `requestTime`, der +den Zeitstempel der HTTP-Anfrage anzeigt und einen, der `validateCookies` genannt wird, der eingehende Cookies validiert. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hallo World!'); +}); + +app.listen(3000); +``` + +### Middleware-Funktion myLogger + +Hier ist ein einfaches Beispiel für eine Middleware-Funktion namens "myLogger". Diese Funktion druckt nur +"LOGGED", wenn eine Anfrage an die App durchläuft. Die Middleware-Funktion wird einer +Variable mit dem Namen `myLogger` zugewiesen. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +Beachten Sie den obigen Aufruf zu `next()`. Beim Aufruf dieser Funktion wird die nächste Middleware-Funktion in +der App aufgerufen. Die `next()` Funktion ist kein Teil des Knotens. s oder Express API, aber ist das dritte +\-Argument, das an die Middleware-Funktion übergeben wird. Die `next()` Funktion kann alles benannt werden, +, aber nach der Konvention wird sie immer als "weiter" bezeichnet. Um Verwirrung zu vermeiden, verwenden Sie immer dieses Übereinkommen. + + + +Um die Middleware-Funktion zu laden, rufen Sie `app.use()` auf, indem Sie die Middleware-Funktion angeben. +Zum Beispiel lädt der folgende Code die `myLogger` Middleware-Funktion vor der Route zum Root-Pfad (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console. og('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Hallo World!'); +}); + +app.listen(3000); +``` + +Jedes Mal, wenn die App eine Anfrage erhält, gibt sie die Nachricht "LOGGED" auf das Terminal aus. + +Die Reihenfolge des Laden von Middleware ist wichtig: Middleware-Funktionen, die zuerst geladen werden, werden auch zuerst ausgeführt. + +Wenn `myLogger` nach der Route zum Wurzelpfad geladen wird, erreicht die Anfrage nie und die App druckt nicht "LOGGED", da der Route-Handler des Root-Pfades den Request-Antwort-Zyklus beendet. + +Die Middleware-Funktion `myLogger` druckt einfach eine Nachricht, übergibt dann die Anfrage an die nächste Middleware-Funktion im Stack durch Aufruf der `next()` Funktion. + +### Middleware-Funktionsanfragezeit + +Als nächstes erstellen wir eine Middleware-Funktion namens "requestTime" und fügen eine Eigenschaft namens `requestTime` +dem Anfrageobjekt hinzu. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +Die App verwendet nun die „requestTime“-Middleware-Funktion. Auch die Callback-Funktion der Root-Pfadroute verwendet die Eigenschaft, die die Middleware-Funktion zu `req` hinzufügt (das Anfrageobjekt). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app.get('/', (req, res) => { + let responseText = 'Hello World!
'; + responseText += `Requested at: ${req.requestTime}`; + res.send(responseText); +}); + +app.listen(3000); +``` + +Wenn Sie eine Anfrage an das Stammverzeichnis der App stellen, zeigt die App nun den Zeitstempel Ihrer Anfrage im Browser an. + +### Middleware-Funktion validateCookies + +Schließlich erstellen wir eine Middleware-Funktion, die eingehende Cookies validiert und eine 400 Antwort schickt, wenn Cookies ungültig sind. + +Hier ist eine Beispielfunktion, die Cookies mit einem externen Asynchrondienst überprüft. + +```js +async function cookieValidator(cookies) { + try { + wait externallyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Ungültige Cookies'); + } +} +``` + +Hier verwenden wir die [`cookie-parser`](/en/resources/middleware/cookie-parser) Middleware, um eingehende Cookies vom `req` Objekt zu analysieren und sie an unsere `cookieValidator` Funktion zu übergeben. Die `validateCookies` Middleware gibt ein Versprechen zurück, das bei Ablehnung automatisch unseren Fehlerhandler auslöst. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('. cookieValidator'); + +const app = express(); + +async function validateCookies(req, res, next) { + wartet cookieValidator(req. ookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// Fehlerbehandler +app. se(err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Beachte, wie `next()` nach `wait cookieValidator(req.cookies)` aufgerufen wird. Dies stellt sicher, dass, wenn +`cookieValidator` auflöst, die nächste Middleware im Stack aufgerufen wird. Wenn du etwas +an die `next()` Funktion übergibt (außer den String `'route'` oder `'router'`), Express betrachtet die aktuelle +Anfrage als Fehler und überspringt alle verbleibenden Funktionen zur Fehlerbehandlung und Middleware +. + + + +Weil Sie Zugriff auf das Anfrageobjekt, das Antwortobjekt, die nächste Middleware-Funktion im Stapel und den gesamten Knoten haben. s API, die Möglichkeiten mit Middleware-Funktionen sind endlos. + +Für weitere Informationen über Express Middleware siehe: [Express Middleware](/en/guide/using-middleware). + +## Konfigurierbare Middleware + +Wenn Sie Ihre Middleware konfigurieren müssen, exportieren Sie eine Funktion, die ein Optionsobjekt oder andere Parameter akzeptiert, , die dann die Middleware-Implementierung basierend auf den Eingabeparametern zurückgibt. + +Datei: `my-middleware.js` + +```js +modul. xports = function (options) { + return function (req, res, next) { + // Implementierung der Middleware-Funktion basierend auf dem Options-Objekt + next(); + }; +}; +``` + +Die Middleware kann nun wie unten gezeigt verwendet werden. + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Siehe [cookie-session](https://github.com/expressjs/cookie-session) und [compression](https://github.com/expressjs/compression) für Beispiele konfigurierbarer Middleware. diff --git a/src/content/docs/de/4x/starter/basic-routing.mdx b/src/content/docs/de/4x/starter/basic-routing.mdx new file mode 100644 index 0000000000..3b2a6d130d --- /dev/null +++ b/src/content/docs/de/4x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Basisrouting +description: Lernen Sie die Grundlagen des Routings in Express.js Anwendungen kennen, wie Sie Routen definieren, HTTP-Methoden handhaben und Routenhandler für Ihren Webserver erstellen. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* bezieht sich darauf, wie eine Anwendung auf einen bestimmten Endpunkt antwortet , die eine URI (oder Pfad) und eine bestimmte HTTP-Request-Methode (GET, POST usw.) ist. + +Jede Route kann eine oder mehrere Handler-Funktionen haben, die ausgeführt werden, wenn die Route übereinstimmt. + +Die Routendefinition nimmt folgende Struktur ein: + +```js +app.METHOD(PATH, HANDLER); +``` + +Wo: + +* `app` ist eine Instanz von `express `. +* `METHOD` ist eine [HTTP-Anfrage-Methode](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in Kleinbuchstaben. +* `PATH` ist ein Pfad auf dem Server. +* `HANDLER` ist die Funktion, die ausgeführt wird, wenn die Route übereinstimmt. + + + +Dieses Tutorial setzt voraus, dass eine Instanz von `express ` namens `app` erstellt wird und der Server +läuft. Wenn du nicht vertraut bist, eine App zu erstellen und sie zu starten, schau dir das Hallo Welt +Beispiel. + + + +Die folgenden Beispiele veranschaulichen die Definition einfacher Routen. + +Antworte mit `Hallo World!` auf der Homepage: + +```js +app.get('/', (req, res) => { + res.send('Hallo Welt!'); +}); +``` + +Antwort auf eine POST-Anfrage auf der Root-Route (`/`), der Startseite der Anwendung: + +```js +app.post('/', (req, res) => { + res.send('Hat eine POST-Anfrage'); +}); +``` + +Antworte auf eine PUT-Anfrage auf die `/user`-Route: + +```js +app.put('/user', (req, res) => { + res.send('Eine PUT-Anfrage bei /user'); +}); +``` + +Antworte auf eine LÖSCHE Anfrage auf die `/user`-Route: + +```js +app.delete('/user', (req, res) => { + res.send('Erhalte eine DELETE Anfrage unter /user'); +}); +``` + +Weitere Details zum Routen finden Sie im [Routing Guide](/en/guide/routing). diff --git a/src/content/docs/de/4x/starter/examples.mdx b/src/content/docs/de/4x/starter/examples.mdx new file mode 100644 index 0000000000..63df3debad --- /dev/null +++ b/src/content/docs/de/4x/starter/examples.mdx @@ -0,0 +1,45 @@ +--- +title: Express-Beispiele +description: Entdecken Sie eine Sammlung von Express.js Anwendungsbeispielen, die verschiedene Anwendungsfälle, Integrationen und erweiterte Konfigurationen umfassen, um Ihnen zu helfen Ihre Projekte zu erlernen und zu bauen. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Authentifizierung mit Login und Passwort +* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - HTTP-Inhaltsaushandlung +* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Arbeiten mit Cookie-basierten Sitzungen +* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Arbeiten mit Cookies +* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Übertragung von Dateien zum Client +* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Arbeiten mit eingebetteten JavaScript-Vorlagen (ejs) +* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Fehlerseiten erstellen +* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Mit Fehler-Middleware arbeiten +* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Einfacher Anfragehandler +* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown als Template-Engine +* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Mit mehreren Express-Routern arbeiten +* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - Controller im MVC-Stil +* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Verfolgung der Online-Benutzeraktivität mit `online` und `redis` Paketen +* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Arbeiten mit Routenparametern +* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Mehrere HTTP-Operationen auf derselben Ressource +* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Routen mit einer Karte organisieren +* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Mit Route Middleware arbeiten +* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Routen pro Ressource organisieren +* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Such-API +* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - Benutzersitzungen +* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Serviere statische Dateien +* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Arbeiten mit virtuellen Hosts +* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Ansichten dynamisch rendern +* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Speichern von Daten im Anfrageobjekt zwischen Middleware-Aufrufen +* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Einfacher API-Dienst + +## Zusätzliche Beispiele + +Dies sind einige zusätzliche Beispiele mit umfassenderen Integrationen. + + + Diese Informationen beziehen sich auf Sites, Produkte oder Module, die nicht vom + Expressjs Team betreut werden. Die Auflistung hier stellt keine Billigung oder Empfehlung des Projektteams von + Expressjs dar. + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Vollstack App mit Express und Next.js mit [Prisma](https://www.npmjs.com/package/prisma) als ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API mit Express in TypeScript mit [Prisma](https://www.npmjs.com/package/prisma) als ORM diff --git a/src/content/docs/de/4x/starter/faq.md b/src/content/docs/de/4x/starter/faq.md new file mode 100644 index 0000000000..8df0cc1a28 --- /dev/null +++ b/src/content/docs/de/4x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: FAQ +description: Finden Sie Antworten auf häufig gestellte Fragen zu Express.js, darunter Themen wie Anwendungsstruktur, Modelle, Authentifizierung, Template-Engines, Fehlerbehandlung und mehr. +--- + +## Wie kann ich meine Anwendung strukturieren? + +Auf diese Frage gibt es keine endgültige Antwort. Die Antwort hängt von +vom Umfang Ihrer Anwendung und dem beteiligten Team ab. Um so flexibel wie möglich +zu sein, macht Express keine Annahmen in Bezug auf die Struktur. + +Routen und andere anwendungsspezifische Logik können in beliebig vielen Dateien +in beliebiger Verzeichnisstruktur gespeichert werden. Folgende +Beispiele für Inspirationen anzeigen: + +- [Route Listings](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Routenplane](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Außerdem gibt es Erweiterungen von Drittanbietern für Express, die einige dieser Muster vereinfachen: + +- [Ressourcenreiches Routen](https://github.com/expressjs/express-resource) + +## Wie definiere ich Modelle? + +Express hat keine Vorstellung von Datenbanken. Dieses Konzept ist +bis zu Drittanbieter-Knotenmodulen übrig und erlaubt Ihnen eine +Schnittstelle mit fast jeder Datenbank. + +Siehe [LoopBack](http://loopback.io) für ein Express-basiertes Framework, das um Modelle zentriert ist. + +## Wie kann ich Benutzer authentifizieren? + +Authentifizierung ist ein anderer Bereich, in dem sich Express nicht +wagt. Sie können ein beliebiges Authentifizierungsschema verwenden. +Für ein einfaches Benutzername/Passwort-Schema, siehe [dieses Beispiel](https://github.com/expressjs/express/tree/master/examples/auth). + +## Welche Template-Engines unterstützt Express? + +Express unterstützt jede Template-Engine, die mit der Signatur `(Pfad, locals, callback)` übereinstimmt. +Um die Schnittstellen der Template-Engine und das Caching zu normalisieren, lesen Sie bitte +[consolidate.js](https://github.com/visionmedia/consolidate.js) +Projekt für Unterstützung. Nicht aufgelistete Template-Engines könnten die Express-Signatur trotzdem unterstützen. + +Weitere Informationen finden Sie unter [Template-Engines mit Express](/en/guide/using-template-engines). + +## Wie gehe ich mit 404 Antworten um? + +In Express sind 404 Antworten nicht das Ergebnis eines Fehlers, daher wird die Middleware von +nicht erfasst. Dieses Verhalten ist +, da eine 404-Antwort einfach das Fehlen zusätzlicher Arbeit anzeigt; +in anderen Worten, Express hat alle Middleware-Funktionen und -Routen ausgeführt, +und festgestellt, dass keiner von ihnen reagiert hat. Alles, was Sie +tun müssen, ist eine Middleware-Funktion am unteren Ende des Stacks (unter allen anderen Funktionen) +hinzuzufügen, um eine 404-Antwort zu handhaben: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Fügen Sie Routen dynamisch zur Laufzeit einer Instanz von `express.Router()` +hinzu, so dass die Routen nicht durch eine Middleware-Funktion ersetzt werden. + +## Wie kann ich einen Fehler einrichten? + +Du definierst die Middleware wie andere Middleware, +außer mit vier anstatt drei, spezifisch mit der Signatur `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Weitere Informationen finden Sie unter [Fehlerbehandlung](/en/guide/error-handling). + +## Wie kann ich plain HTML rendern? + +Du bist es nicht! Es gibt keine Notwendigkeit HTML mit der Funktion `res.render()` zu "render". +Wenn du eine bestimmte Datei hast, nutze die Funktion `res.sendFile()`. +Wenn du viele Assets aus einem Verzeichnis lieferst, verwende die `express.static()` +Middleware-Funktion. + +## Welche Version von Node.js benötigt Express? + +- [Express 4.x](/en/4x/api) benötigt Node.js 0.10 oder höher. +- [Express 5.x](/en/5x/api) benötigt Node.js 18 oder höher. diff --git a/src/content/docs/de/4x/starter/generator.mdx b/src/content/docs/de/4x/starter/generator.mdx new file mode 100644 index 0000000000..4559bace00 --- /dev/null +++ b/src/content/docs/de/4x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Express-Applikationsgenerator +description: Lernen Sie, wie Sie mit dem Express-Anwendungsgenerator-Tool schnell ein Skelett für Ihre Express.js-Anwendungen erstellen, die Einrichtung optimieren und die Konfiguration optimieren. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Verwenden Sie das Applikationsgenerator-Tool, "express-generator", um schnell ein Anwendungsskelett zu erstellen. + +Du kannst den Anwendungsgenerator mit dem Befehl `npx` ausführen (verfügbar in Node.js 8.2.0). + +```bash +$ npx Express-Generator +``` + +Für frühere Node-Versionen installieren Sie den Anwendungsgenerator als globales npm-Paket und starten es dann: + +```bash +$ npm Installation -g Express-Generator +$ express +``` + +Zeige die Befehlsoptionen mit der `-h` Option: + +```bash +$ express -h + + Verwendung: Express [options] [dir] + + Optionen: + + -h, --help Ausgabe-Informationen + --version Ausgabe der Versionsnummer + -e, --ejs add ejs engine support + --hbs add handlebars engine support + --pug add pug engine support + -H, --hogan add hogan. s Engine Unterstützung + --no-view generieren ohne View Engine + -v, --view add view support (ejs|hbs|hjs|jade|pug|twig|vash) (defaults to jade) + -c, --css Fügen Sie Stylesheet Unterstützung (less |stylus|compass|sass) (standardmäßig auf plain css) + --git add . itignore + -f, --force auf nicht leeres Verzeichnis +``` + +Zum Beispiel erstellt das Folgende eine Express-App namens *myapp*. Die App wird in einem Ordner namens *myapp* im aktuellen Arbeitsverzeichnis erstellt und die View Engine wird auf Mops gesetzt: + +```bash +$ express --view=pug myapp + + erstellen : myapp + create : myapp/package.json + create : myapp/app. s + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index. s + erstellen : myapp/routes/users. s + create : myapp/public/stylesheets + create : myapp/public/stylesheets/style. ss + erstellen : myapp/views + erstellen : myapp/views/index. ug + erstellen : myapp/views/layout.pug + erstellen : myapp/views/error. ug + erstellen : myapp/bin + erstellen : myapp/bin/www +``` + +Installieren Sie dann Abhängigkeiten: + +```bash +$ cd myapp +$ npm Installation +``` + +Führen Sie auf MacOS oder Linux die App mit diesem Befehl aus: + +```bash +$ DEBUG=myapp:* npm Start +``` + +Benutzen Sie auf Windows Befehlsaufforderung folgenden Befehl: + +```bash +> DEBUG=myapp:* & npm Start setzen +``` + +Verwenden Sie unter Windows PowerShell, diesen Befehl: + +```bash +PS> $env:DEBUG='myapp:*'; npm Start +``` + +Lade dann `http://localhost:3000/` in deinem Browser, um auf die App zuzugreifen. + +Die generierte App hat folgende Verzeichnisstruktur: + +```bash +. + 本 app.js + 本 bin + www + 本 Paket. son + 文 public + Bilder + javascripts + Stylesheets + style. ss + 本 routet + index.js + Benutzer. s + 本 Ansichten + Fehler. ug + 本 index.pug + layout.pug + +7 Verzeichnisse, 9 Dateien +``` + + + +Die vom Generator erstellte App-Struktur ist nur eine von vielen Möglichkeiten, Express-Apps zu strukturieren. +Fühlen Sie sich frei, diese Struktur zu verwenden oder sie so zu modifizieren, dass sie Ihren Bedürfnissen am besten entspricht. + + diff --git a/src/content/docs/de/4x/starter/hello-world.mdx b/src/content/docs/de/4x/starter/hello-world.mdx new file mode 100644 index 0000000000..12f7b3f36c --- /dev/null +++ b/src/content/docs/de/4x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Hallo Weltbeispiel +description: Beginnen Sie mit Express.js, indem Sie eine einfache 'Hallo World'-Anwendung erstellen, die die Grundeinstellung und die Servererstellung für Anfänger demonstriert. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Eingebettet unten ist im Wesentlichen die einfachste Express-App, die Sie erstellen können. Es ist eine einzelne Datei-App +— *not* was Sie bekommen würden, wenn Sie den [Express-Generator](/en/starter/generator), welche +das Gerüst für eine vollständige Anwendung mit zahlreichen JavaScript-Dateien, Jade-Vorlagen und +Unterverzeichnissen für verschiedene Zwecke erstellt. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res. end('Hallo World!'); +}); + +app.listen(port, () => { + console.log(`Beispiel-App, die auf Port ${port}`); +}); +``` + +Diese App startet einen Server und lauscht auf Port 3000 für Verbindungen. The app responds with "Hello World!" for requests +to the root URL (`/`) or *route*. Für jeden anderen Pfad wird es mit einem **404 Nicht gefunden** antworten. + +## Lokal laufen + +Erstelle zuerst ein Verzeichnis namens `myapp`, ändere es und führe `npm init` aus. Installieren Sie dann `Expres` als Abhängigkeit, wie in der [Installationsanleitung](/en/starter/installing). + +Erstelle im `myapp` Verzeichnis eine Datei namens `app.js` und kopiere den Code aus dem obigen Beispiel. + + + +Die `req` (Anfrage) und `res` (Antwort) sind genau die gleichen Objekte, die der Knoten anbietet, also kann +`req aufrufen. ipe()`, `req.on('data', callback)` und alles, was Sie sonst ohne Express +tun würden. + + + +Führen Sie die App mit dem folgenden Befehl aus: + +```bash +$ node app.js +``` + +Lade dann `http://localhost:3000/` in einem Browser, um die Ausgabe zu sehen. diff --git a/src/content/docs/de/4x/starter/installing.mdx b/src/content/docs/de/4x/starter/installing.mdx new file mode 100644 index 0000000000..bee85fe973 --- /dev/null +++ b/src/content/docs/de/4x/starter/installing.mdx @@ -0,0 +1,50 @@ +--- +title: Installiere +description: Erfahren Sie, wie Sie Express.js in Ihrer Node.js-Umgebung installieren, einschließlich der Einrichtung Ihres Projektverzeichnisses und der Verwaltung von Abhängigkeiten mit npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Bevor Sie beginnen, stellen Sie sicher, dass Sie [Node.js](https://nodejs.org/) 0.10 oder höher installiert haben. Erstellen Sie dann ein Verzeichnis für Ihre Anwendung und navigieren Sie hinein. + +```bash +mkdir myapp +cd myapp +``` + +Benutze den Befehl `npm init` um eine `package.json` Datei für deine Anwendung zu erstellen. +Für weitere Informationen darüber, wie `package.json` funktioniert, siehe [Spezifikationen für npm's package.json handling](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +Dieser Befehl fragt Sie nach einer Reihe von Dingen wie dem Namen und der Version Ihrer Anwendung. +Im Moment können Sie einfach RETURN drücken, um die Standardwerte für die meisten von ihnen zu akzeptieren, mit der folgenden Ausnahme: + +``` +eintragspunkt: (index.js) +``` + +Geben Sie `app.js` ein, oder was auch immer der Name der Hauptdatei sein soll. Wenn Sie `index.js` wollen, drücken Sie RETURN um den empfohlenen Dateinamen zu akzeptieren. + +Installieren Sie jetzt Express im `myapp` Verzeichnis und speichern Sie es in der Abhängigkeitsliste. Zum Beispiel: + +```bash +npm Express installieren +``` + +Um Express vorübergehend zu installieren und nicht zur Abhängigkeitsliste hinzufügen: + +```bash +npm express installieren --no-save +``` + + + +Standardmäßig fügt `npm install` mit Version npm 5.0+ das Modul der `dependencies` Liste im +`package hinzu. son` file; mit früheren Versionen von npm musst du die `--save` Option +explizit angeben. Danach wird das Ausführen von `npm install` im App-Verzeichnis automatisch +Module in der Abhängigkeitsliste installiert. + + diff --git a/src/content/docs/de/4x/starter/static-files.mdx b/src/content/docs/de/4x/starter/static-files.mdx new file mode 100644 index 0000000000..f1c8dc894a --- /dev/null +++ b/src/content/docs/de/4x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Serviere statische Dateien in Express +description: Verstehen Sie, wie Sie statische Dateien wie Bilder, CSS und JavaScript in Express.js Anwendungen mit der integrierten 'static' Middleware bedienen können. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Um statische Dateien wie Bilder, CSS-Dateien und JavaScript-Dateien bereitzustellen, verwenden Sie die in Express integrierte Middleware-Funktion `express.static`. + +Die Funktionssignatur ist: + +```js +express.static(root, [options]); +``` + +Das `root` Argument gibt das Wurzelverzeichnis an, von dem aus statische Assets ausgeliefert werden sollen. +Für weitere Informationen zum Argument `options` siehe [express.static](/en/5x/api#express.static). + +Verwenden Sie zum Beispiel den folgenden Code, um Bilder, CSS-Dateien und JavaScript-Dateien in einem Verzeichnis mit dem Namen `public` auszugeben: + +```js +app.use(express.static('public')); +``` + +Jetzt kannst du die Dateien im `public` Verzeichnis laden: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express sucht die Dateien relativ zum statischen Verzeichnis, so dass der Name des statischen Verzeichnisses +nicht Teil der URL ist. + + + +Um mehrere statische Asset-Verzeichnisse zu verwenden, rufen Sie die `express.static` Middleware-Funktion mehrmals auf: + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express sucht die Dateien in der Reihenfolge, in der du die statischen Verzeichnisse mit der Middleware-Funktion `express.static` gesetzt hast. + + + +Für beste Ergebnisse Benutze einen Reverse +Proxy Cache um die Leistung von +zu verbessern und statische Assets zu bedienen. + + + +Um einen virtuellen Pfad-Präfix zu erstellen (wo der Pfad existiert eigentlich nicht im Dateisystem) für Dateien, die durch die `express. tatic` Funktion, [einen Mount-Pfad angeben](/en/5x/api#app.use) für das statische Verzeichnis angeben, wie unten angezeigt: + +```js +app.use('/static', express.static('public')); +``` + +Nun kannst du die Dateien, die sich im `public` Verzeichnis befinden, aus dem `/static` Pfadpräfix laden. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +Der Pfad, den du der `express.static` Funktion zur Verfügung stellst, ist jedoch relativ zu dem Verzeichnis, von dem aus du deinen `node` Prozess startest. Wenn Sie die Express-App aus einem anderen Verzeichnis ausführen, ist es sicherer, den absoluten Pfad des Verzeichnisses zu verwenden, das Sie verwenden möchten: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public')); +``` + +Weitere Informationen über die `serve-static` Funktion und ihre Optionen finden Sie unter [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/de/5x/advanced/developing-template-engines.md b/src/content/docs/de/5x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..243960da6a --- /dev/null +++ b/src/content/docs/de/5x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Template-Engines für Express entwickeln +description: Erfahren Sie, wie Sie mithilfe von app.engine() benutzerdefinierte Template-Engines für Express.js entwickeln können, mit Beispielen zur Erstellung und Integration Ihrer eigenen Template-Rendering-Logik. +--- + +Benutze die `app.engine(ext, callback)` Methode, um deine eigene Template-Engine zu erstellen. `ext` bezieht sich auf die Dateierweiterung, und `callback` ist die Template-Engine-Funktion, , die die folgenden Elemente als Parameter akzeptiert: den Speicherort der Datei, das Optionsobjekt und die Callback-Funktion. + +Der folgende Code ist ein Beispiel für die Implementierung einer sehr einfachen Template-Engine zum Rendern von `.ntl` Dateien. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +Deine App wird nun in der Lage sein, `.ntl`-Dateien zu rendern. Erstelle eine Datei namens `index.ntl` im `views` Verzeichnis mit folgendem Inhalt. + +```pug +#title# +#message# +``` + +Erstellen Sie dann die folgende Route in Ihrer App. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +Wenn du eine Anfrage an die Startseite stellt, wird `index.ntl` als HTML dargestellt. diff --git a/src/content/docs/de/5x/guide/behind-proxies.mdx b/src/content/docs/de/5x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..786e7aff5f --- /dev/null +++ b/src/content/docs/de/5x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Express hinter Proxies +description: Lernen Sie, wie Sie Express.js Anwendungen so konfigurieren, dass sie hinter Reverse Proxies korrekt arbeiten, einschließlich der Trust-Proxy-Einstellung für Client-IP-Adressen. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Wenn Sie eine Express-App hinter einem Reverse Proxy ausführen, können einige der Express-APIs andere Werte als erwartet zurückgeben. Um dies anzupassen die Einstellung `trust proxy` kann verwendet werden, um Informationen auszublenden, die vom Reverse Proxy in den Express API bereitgestellt werden. Das häufigste Problem sind Express-APIs, die die IP-Adresse des Clients offenlegen, statt dessen eine interne IP-Adresse des Reverse Proxy anzeigen. + + + +Bei der Konfiguration der `trust proxy` Einstellung ist es wichtig, das genaue Setup des +Reverse Proxy zu verstehen. Da diese Einstellung den in der Anfrage angegebenen Werten vertrauen wird Es ist wichtig, dass +die Kombination der Einstellung in Express mit der Funktionsweise des Reverse Proxy übereinstimmt. + + + +Die Anwendungseinstellung `trust proxy` kann auf einen der in der folgenden Tabelle aufgelisteten Werte gesetzt werden. + + + + + + + + + + + + + + + + + + + + + +
TypWert
Boolean +Wenn `true`, wird die IP-Adresse des Clients als linker Eintrag im `X-Forwarded-For` Header verstanden. + +Falls „falsch“ die App als direkt gegenüber dem Client verstanden wird und die IP-Adresse des Clients von „req.socket.remoteAddress“ abgeleitet wird. Dies ist die Standardeinstellung. + + +Wenn Sie auf `true` setzen, ist es wichtig sicherzustellen, dass der letzte Reverse Proxy alle folgenden HTTP-Header löscht/überschreibt: `X-Forwarded-For`, `X-Forwarded-Host` und `X-Forwarded-Proto`, andernfalls ist es möglich, dass der Client irgendeinen Wert angibt. + +
IP-Adressen +Eine IP-Adresse, ein Subnetz oder ein Array von IP-Adressen und Subnetzen, die darauf vertrauen, dass es sich um einen Reverse Proxy handelt. Die folgende Liste zeigt die vorkonfigurierten Subnetznamen an: + +* loopback - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +Sie können IP-Adressen auf jede der folgenden Arten festlegen: + +```js +app.set('trust proxy', 'loopback'); // ein einzelnes Subnetz +app.set('trust proxy', 'loopback, 123.123.123.123''); // ein Subnetz und eine Adresse +angeben. et('trust proxy', 'loopback, linklocal, uniquelocal'); // mehrere Subnetze als CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // mehrere Subnetze als Array angeben +``` + +Wenn angegeben, werden die IP-Adressen oder Subnetze vom Prozess der Adressermittlung ausgeschlossen und die dem Anwendungsserver nächstgelegene nicht vertrauenswürdige IP-Adresse wird als IP-Adresse des Clients ermittelt. Dies funktioniert indem überprüft wird, ob `req.socket.remoteAddress` vertrauenswürdig ist. Wenn ja, dann wird jede Adresse in `X-Forwarded-For` von rechts nach links bis zur ersten Adresse überprüft, die nicht vertrauenswürdig ist. + +
Nummer +Benutzen Sie die Adresse, die höchstens `n` von der Express-Anwendung entfernt ist. `req.socket.remoteAddress` ist der erste Hop, und der Rest wird im `X-Forwarded-For` Header von rechts nach links gesucht. Ein Wert von `0` bedeutet, dass die erste nicht vertrauenswürdige Adresse `req.socket.remoteAddress` ist, d.h. es gibt keinen Reverse-Proxy. + + +Bei der Verwendung dieser Einstellung ist es wichtig sicherzustellen, dass es keine Multiple gibt, verschiedene Pfade zur Express-Anwendung, so dass der Client kleiner sein kann als die konfigurierte Anzahl von Hops, die entfernt sind andernfalls kann es möglich sein, dass der Kunde irgendeinen Wert angibt. + +
Funktion +Benutzerdefinierte Vertrauens-Implementierung. + +```js +app.set('trust proxy', (ip) => { + if (ip === '127.0.0.1' || ip === '123.123.123. 23') + return true; // vertrauenswürdige IPs + else return false; +}); +``` + +
+ +Das Aktivieren von `trust proxy` hat folgende Auswirkungen: + +
    +
  • + Der Wert von [req.hostname](/en/api#req.hostname) wird vom Wert abgeleitet, der im + `X-Forwarded-Host` Header gesetzt wurde , die vom Client oder vom Proxy gesetzt werden kann. +
    • +
  • + `X-Forwarded-Proto` kann vom Reverse Proxy gesetzt werden, um der App mitzuteilen, ob es `https` oder + `http` oder sogar ein ungültiger Name ist. Dieser Wert wird von [req.protocol]reflektiert (/en/api#req.protocol). +
    • +
  • + Die Werte [req.ip](/en/api#req.ip) und [req.ips](/en/api#req.ips) werden auf der Basis der + Socket-Adresse und des `X-Forwarded-For` Headers gefüllt beginnend an der ersten nicht vertrauenswürdigen Adresse. +
    • +
+ +Die `trust proxy` Einstellung ist mit dem [proxy-addr](https://www.npmjs.com/package/proxy-addr) Paket implementiert. Weitere Informationen finden Sie in der Dokumentation. diff --git a/src/content/docs/de/5x/guide/debugging.mdx b/src/content/docs/de/5x/guide/debugging.mdx new file mode 100644 index 0000000000..44802397e8 --- /dev/null +++ b/src/content/docs/de/5x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Debuggen Express +description: Erfahren Sie, wie Sie Debugging-Logs in Express.js-Anwendungen aktivieren und nutzen können, indem Sie die DEBUG-Umgebungsvariable für verbesserte Fehlerbehebung setzen. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Um alle internen Logs zu sehen, die in Express verwendet werden, setzen Sie die Umgebungsvariable `DEBUG` auf +`express:*` beim Starten Ihrer App. + +```bash +$ DEBUG=Express:* node index.js +``` + +Verwenden Sie unter Windows den entsprechenden Befehl. + +```bash +> $env:DEBUG = "Express:*"; node index.js +``` + +Das Ausführen dieses Befehls auf der vom [Express-Generator] generierten Standard-App (/en/starter/generator) gibt folgende Ausgabe aus: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +Wenn eine Anfrage an die App gestellt wird, sehen Sie die im Express-Code angegebenen Protokolle: + +```bash + express :router dispatching GET / +4h + express :router query : / +2ms + express :router expresInit : / +0ms + express:router favicon : / +0ms + express :router logger : / +1ms + express :router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express :router cookieParser : / +0ms + express:router stylus : / +0ms + express :router serveStatic : / +2ms + express :router router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index. ug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +Um die Protokolle nur von der Router-Implementierung zu sehen, setzen Sie den Wert `DEBUG` auf `express:router`. Um Protokolle nur von der Anwendungsimplementierung zu sehen, setzten Sie den Wert von `DEBUG` auf `express:application`, und so weiter. + +## Anwendungen generiert von `Express` + +Eine Anwendung, die durch den Befehl `express generiert` erzeugt wird, benutzt das Modul `debug` und sein Debug-Namensraum wird auf den Namen der Anwendung übertragen. + +Wenn Sie zum Beispiel die App mit `$ express Beispiel-App` erstellt haben, können Sie die Debug-Anweisungen mit folgendem Befehl aktivieren: + +```bash +$ DEBUG=Beispiel-app:* Knoten ./bin/www +``` + +Sie können mehr als einen Debug-Namensraum angeben, indem Sie eine kommaseparierte Namensliste zuweisen: + +```bash +$ DEBUG=http,mail,Express:* node index.js +``` + +## Erweiterte Optionen + +Wenn Sie über Node.js laufen, können Sie ein paar Umgebungsvariablen festlegen, die das Verhalten der Debug-Protokollierung ändern: + +| Name | Zweck | +| ------------------- | --------------------------------------------------------------------------- | +| `DEBUG` | Aktiviere/deaktiviert bestimmte Debugging-Namensräume. | +| DEBUG_COLORS | Gibt an, ob Farben in der Debug-Ausgabe verwendet werden sollen oder nicht. | +| DEBUG_DEPTH\` | Objektüberprüfungstiefe. | +| `DEBUG_FD` | Datei-Deskriptor, in den die Debug-Ausgabe geschrieben wird. | +| `DEBUG_SHOW_HIDDEN` | Zeigt versteckte Eigenschaften auf untersuchten Objekten. | + + + +Die Umgebungsvariablen, die mit `DEBUG_` beginnen, werden am Ende in ein Optionsobjekt +konvertiert, das mit `%o`/`%O` Formate verwendet wird. Siehe die Dokumentation von Node.js für +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) für die vollständige +Liste. + + diff --git a/src/content/docs/de/5x/guide/error-handling.mdx b/src/content/docs/de/5x/guide/error-handling.mdx new file mode 100644 index 0000000000..d3d51364b4 --- /dev/null +++ b/src/content/docs/de/5x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Fehler beim Umgang +description: Verstehen Sie, wie Express.js Fehler im synchronen und asynchronen Code behandelt, und lernen Sie, benutzerdefinierte Fehlerbehandlung Middleware für Ihre Anwendungen zu implementieren. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Error Handling* bezieht sich darauf, wie Express Fehler fängt und verarbeitet, die +sowohl synchron als auch asynchron auftritt. Express kommt mit einem Standardfehler +\-Handler, damit Sie nicht Ihren eigenen schreiben müssen, um loszulegen. + +## Fehler beim Fangen + +Es ist wichtig sicherzustellen, dass Express alle Fehler, die auftreten, während +Routen-Handler und Middleware ausführt. + +Fehler, die im synchronen Code innerhalb von Routenhandlern und Middleware +auftreten, erfordern keine zusätzliche Arbeit. If synchronous code throws an error, then Express will +catch and process it. Zum Beispiel: + +```js +app.get('/', (req, res) => { + werfen neue Fehler ('BROKEN'); // Express fängt dies auf eigene Faust. +}); +``` + +For errors returned from asynchronous functions invoked by route handlers +and middleware, you must pass them to the `next()` function, where Express will +catch and process them. Zum Beispiel: + +```js +app.get('/', (req, res, next) => { + fs. eadFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Fehler an Express übergeben. + } else { + res. end(data); + } + }); +}); +``` + +Starting with Express 5, route handlers and middleware that return a Promise +will call `next(value)` automatically when they reject or throw an error. +Zum Beispiel: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = wait getUserById(req.params.id); + res.send(user); +}); +``` + +Wenn `getUserById` einen Fehler oder eine Ablehnung, wird `next` entweder mit +dem Wurffehler oder dem abgelehnten Wert aufgerufen. Wenn kein abgelehnter Wert angegeben wird, wird `next` +mit einem Standard-Fehlerobjekt aufgerufen, das vom Express-Router bereitgestellt wird. + +Wenn du etwas an die `next()` Funktion übergibt (außer den String `'route'`), +Express betrachtet die aktuelle Anfrage als Fehler und überspringt alle +verbleibenden Funktionen zur Fehlerbehandlung und Middleware. + +Wenn der Rückruf in einer Sequenz keine Daten enthält, nur Fehler, kannst du den Code +wie folgt vereinfachen: + +```js +app.get('/', [ + Funktion (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +Im obigen Beispiel wird `next` als Callback für `fs.writeFile` bereitgestellt, +, das mit oder ohne Fehler aufgerufen wird. Wenn kein Fehler vorliegt, wird der zweite +\-Handler ausgeführt, sonst fängt und verarbeitet Express den Fehler. + +Sie müssen Fehler, die im asynchronen Code auftreten, der von Routenhandlern oder +Middleware aufgerufen wird, auffangen und an Express zur Verarbeitung weiterleiten. Zum Beispiel: + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + next(err); + } + }, 100); +}); +``` + +Das obige Beispiel benutzt einen "try...catch"-Baustein, um Fehler im +asynchronen Code zu fangen und sie an den Express zu übergeben. Wenn der Block `try...catch` +weggelassen wurde, würde Express den Fehler nicht auffinden, da er nicht Teil des synchronen +Handlercodes ist. + +Verwende Versprechungen, um den Overhead des `try...catch`-Bausteins zu vermeiden oder wenn du Funktionen +benutzt, die Versprechen zurückgeben. Zum Beispiel: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + . hen(() => { + werfen neue Fehler ('BROKEN'); + }) + . atch(next); // Fehler werden an Express übergeben. +}); +``` + +Da Versprechungen automatisch sowohl synchrone Fehler als auch abgelehnte Versprechungen fangen, +du kannst einfach `next` angeben, da der letzte Catch Handler und Express Fehler fängt an +weil der Catch-Handler den Fehler als erstes Argument angibt. + +Sie können auch eine Kette von Handlern verwenden, um sich auf synchrone Fehler +zu stützen, indem Sie den asynchronen Code auf etwas Triviales reduzieren. Zum Beispiel: + +```js +app.get('/', [ + Funktion (req, res, next) { + fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals. ata = Daten; + next(err); + }); + }, + function (req, res) { + res. ocals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +Das obige Beispiel hat ein paar triviale Anweisungen aus dem Aufruf `readFile` +. If `readFile` causes an error, then it passes the error to Express, otherwise you +quickly return to the world of synchronous error handling in the next handler +in the chain. Dann versucht das obige Beispiel die Daten zu verarbeiten. Wenn dies fehlschlägt, fängt der Synchron-Fehlerhandler +ihn ab. Hätten Sie diese Verarbeitung innerhalb von +mit dem `readFile` Callback durchgeführt, dann könnte sich die Anwendung beenden und die Express-Fehler +Handler würden nicht laufen. + +Welche Methode Sie auch immer verwenden, wenn Sie wollen, dass Express-Fehlerbehandler aufgerufen werden und die +\-Anwendung überleben soll, Sie müssen sicherstellen, dass Express den Fehler empfängt. + +## Der Standard-Fehlerhandler + +Express kommt mit einem integrierten Fehlerbehandler, der sich um Fehler kümmert, die in der App auftreten könnten. Diese Standard-Middleware-Funktion wird am Ende des Middleware-Funktionstacks hinzugefügt. + +Wenn du einen Fehler an `next()` übergibt und ihn nicht in einem benutzerdefinierten +Handler behandelst, es wird vom eingebauten Fehlerhandler behandelt; wird der Fehler +mit der Stack-Spur an den Client geschrieben. The stack trace is not included +in the production environment. + + + +Setze die Umgebungsvariable `NODE_ENV` auf `production`, um die App im Produktionsmodus auszuführen. + + + +Wenn ein Fehler geschrieben wird, werden folgende Informationen zur Antwort +hinzugefügt: + +* Der `res.statusCode` wurde von `err.status` (oder `err.statusCode`) gesetzt. Wenn + sich dieser Wert außerhalb des 4xx oder 5xx Bereichs befindet, wird er auf 500 gesetzt. +* Die `res.statusMessage` wurde gemäß dem Statuscode gesetzt. +* Der Körper wird der HTML-Code der Statuscode-Nachricht sein, wenn in der Produktion + \-Umgebung, andernfalls 'err.stack' ist. +* Alle in einem `err.headers` Objekt angegebenen Header. + +Wenn du `next()` mit einem Fehler aufruft, nachdem du die +Antwort geschrieben hast (z. B. wenn beim Streamen der +Antwort auf den Client ein Fehler aufgetreten ist), der Express-Standardfehlerhandler schließt die +Verbindung und schlägt die Anfrage fehl. + +Wenn Sie also eine benutzerdefinierte Fehlerbehandlung hinzufügen, müssen Sie den Standard-Express-Fehlerbehandler an +delegieren wenn die Kopfzeilen +bereits an den Client gesendet wurden: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Beachte, dass der Standard-Fehlerhandler ausgelöst werden kann, wenn du `next()` mit einem Fehler +in deinem Code mehrmals aufrufst, auch wenn benutzerdefinierte Fehler beim Umgang mit Middleware vorhanden sind. + +Andere Fehler beim Umgang mit Middleware finden Sie unter [Express Middleware](/en/resources/middleware). + +## Schreibfehler + +Definieren Sie die Middleware-Funktionen wie andere Middleware-Funktionen +außer Funktionen zur Fehlerbehandlung haben vier Argumente anstelle von drei: +`(err, req, res, next)`. Zum Beispiel: + +```js +app.use(((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Etwas kaputt!'); +}); +``` + +Du definierst die Middleware zuletzt nach anderen `app.use()` und Routet Anrufe; zum Beispiel: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser. rlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app. se(methodOverride()); +app.use((err, req, res, next) => { + // Logik +}); +``` + +Antworten innerhalb einer Middleware-Funktion können in jedem Format sein, wie z.B. in einer HTML-Fehlerseite, einer einfachen Nachricht oder einem JSON-String. + +Für organisatorische (und höherstufige Framework) Zwecke können Sie +verschiedene Middleware-Funktionen definieren, so wie Sie es mit den regulären Middleware-Funktionen +würden. Zum Beispiel, um einen Fehlerhandler +für Anfragen mit `XHR` und denen ohne folgende zu definieren: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app. se( + bodyParser.urlencoded({ + extended: true, + }) +); +app. se(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +In diesem Beispiel könnten die generischen `logErrors` Anfrage und +Fehlerinformationen in `stderr` schreiben, zum Beispiel: + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +Auch in diesem Beispiel wird `clientErrorHandler` wie folgt definiert; in diesem Fall wird der Fehler explizit an den nächsten weitergegeben. + +Beachten Sie, dass, wenn *not* in einer Fehlerbehandlungsfunktion "Weiter" aufruft, Sie dafür verantwortlich sind, die Antwort zu schreiben (und zu beenden). Andernfalls werden diese Anträge "hängen" und sind nicht für die Müllsammlung berechtigt. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500). end({ error: 'Something failed!' }); + } else { + next(err); + } +} +``` + +Implementierung der "catch-all" `errorHandler` Funktion wie folgt (zum Beispiel): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +Wenn du einen Route-Handler mit mehreren Callback-Funktionen hast, kannst du den Parameter `route` verwenden, um zum nächsten Route-Handler zu springen. Zum Beispiel: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user. asPaid) { + // weitere Bearbeitung dieser Anfrage + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent. ind((err, doc) => { + if (err) return next(err); + res. son(doc); + }); + } +); +``` + +In diesem Beispiel wird der `getPaidContent` Handler übersprungen, aber alle verbleibenden Handler in `app` für `/a_route_behind_paywall` würden weiterhin ausgeführt werden. + + + +Aufrufe in `next()` und `next(err)` zeigen an, dass der aktuelle Handler abgeschlossen ist und in welchem Zustand ist. +`next(err)` überspringt alle verbleibenden Handler in der Kette mit Ausnahme derjenigen, die bis zu +eingerichtet sind, um Fehler wie oben beschrieben zu handhaben. + + diff --git a/src/content/docs/de/5x/guide/overriding-express-api.md b/src/content/docs/de/5x/guide/overriding-express-api.md new file mode 100644 index 0000000000..e7f6044eb7 --- /dev/null +++ b/src/content/docs/de/5x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Überschreiben der Express-API +description: Erfahren Sie, wie Sie die Express.js API anpassen und erweitern können, indem Sie Methoden und Eigenschaften der Request- und Response-Objekte mittels Prototypen überschreiben. +--- + +Die Express API besteht aus verschiedenen Methoden und Eigenschaften auf den Anfrage- und Antwort-Objekten. Diese werden vom Prototyp geerbt. Es gibt zwei Erweiterungspunkte für die Express API: + +1. Die globalen Prototypen unter `express.request` und `express.response`. +2. App-spezifische Prototypen bei `app.request` und `app.response`. + +Das Ändern der globalen Prototypen wirkt sich auf alle geladenen Express-Apps im selben Prozess aus. Wenn gewünscht, können Änderungen app-spezifisch gemacht werden, indem nur app-spezifische Prototypen nach dem Erstellen einer neuen App geändert werden. + +## Methoden + +Sie können die Signatur und das Verhalten bestehender Methoden mit eigenen überschreiben, indem Sie eine benutzerdefinierte Funktion zuweisen. + +Folgendes ist ein Beispiel für das Überschreiben des Verhaltens von [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +Die obige Implementierung ändert die ursprüngliche Signatur von `res.sendStatus`. Es akzeptiert nun einen Statuscode, Kodierungstyp und die Nachricht, die an den Client gesendet werden soll. + +Die überschriebene Methode kann nun auf diese Weise verwendet werden: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## Eigenschaften + +Eigenschaften in der Express-API sind entweder: + +1. Zugewiesene Eigenschaften (z.B. `req.baseUrl`, `req.originalUrl`) +2. Definiert als Getters (z. B.: `req.secure`, `req.ip`) + +Da Eigenschaften in Kategorie 1 dynamisch auf den `request` und `response` Objekten im Kontext des aktuellen Request-Antwort-Zyklus zugewiesen werden ihr Verhalten kann nicht überschrieben werden. + +Eigenschaften der Kategorie 2 können mit der Express API Extensions API überschrieben werden. + +Der folgende Code schreibt neu wie der Wert von `req.ip` abgeleitet wird. Jetzt gibt es einfach den Wert des `Client-IP` Request-Headers zurück. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Prototyp + +Um die Express API zur Verfügung zu stellen, werden die Anfrage/Antwort-Objekte an Express weitergegeben (via `app(req, res)`, zum Beispiel, müssen von der gleichen Prototypenkette zu erben. Standardmäßig ist dies `http.IncomingRequest.prototype` für die Anfrage und `http.ServerResponse.prototype` für die Antwort. + +Wenn nötig, wird empfohlen, dass dies nur auf der Anwendungsebene und nicht auf globaler Ebene geschieht. Achten Sie auch darauf, dass der verwendete Prototyp die Funktionalität so nah wie möglich an die Standard-Prototypen anpasst. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/de/5x/guide/routing.mdx b/src/content/docs/de/5x/guide/routing.mdx new file mode 100644 index 0000000000..709b3db818 --- /dev/null +++ b/src/content/docs/de/5x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Routing +description: Lernen Sie, wie Sie Routen in Express.js Anwendungen definieren und nutzen können, einschließlich Routenmethoden, Routenpfaden, Parameter und Router für modulare Route. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* bezieht sich darauf, wie die Endpunkte einer Anwendung (URIs) auf Kundenanfragen reagieren. +Für eine Einführung in das Routing siehe [Basic routing](/en/starter/basic-routing). + +Du definierst Routing, indem du Methoden des Express `app` Objekts verwendest, die den HTTP-Methoden entsprechen; +zum Beispiel, `app. et()` um GET-Anfragen und `app.post` zu behandeln, um POST-Anfragen zu bearbeiten. Für eine vollständige Liste +siehe [app.METHOD](/en/5x/api#app.METHOD). Du kannst auch [app.all()](/en/5x/api#app.all) verwenden, um alle HTTP-Methoden und [app. se()](/en/5x/api#app.use) bis +Middleware als Callback-Funktion angeben (siehe [Middleware](/en/guide/using-middleware) für Details). + +Diese Routing-Methoden geben eine Callback-Funktion (manchmal auch "handler functions") an, die aufgerufen wird, wenn die Anwendung eine Anfrage an die angegebene Route (Endpunkt) und die HTTP-Methode erhält. Mit anderen Worten, die Anwendung "lauscht" für Anforderungen, die mit der angegebenen Route(s) und Methode(n) übereinstimmen und wenn es ein Spiel erkennt, ruft es die angegebene Callback-Funktion auf. + +In der Tat können die Routing-Methoden mehr als eine Callback-Funktion als Argumente haben. +Mit mehreren Callback-Funktionen, es ist wichtig, `next` als Argument für die Callback-Funktion zur Verfügung zu stellen und dann `next()` im Körper der Funktion aufzurufen, um die Steuerung +an den nächsten Callback zu übergeben. + +Der folgende Code ist ein Beispiel für eine sehr einfache Route. + +```js +const express = require('express '); +const app = express = ); + +// Mit "Hallo world" antworten, wenn eine GET-Anfrage an die Homepage +App gestellt wird. et('/', (req, res) => { + res.send('Hallo Welt'); +}); +``` + +## Routenmethoden + +Eine Route-Methode wird von einer der HTTP-Methoden abgeleitet und an eine Instanz der Klasse \`express angehängt. + +Der folgende Code ist ein Beispiel für Routen, die für die `GET` und die `POST` Methoden im Root der App definiert sind. + +```js +// GET Methode Route +app.get('/', (req, res) => { + res. end('GET request to the homepage'); +}); + +// POST method route +app. ost('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Express unterstützt Methoden, die allen HTTP-Anfragemethoden entsprechen: `get`, `post` und so weiter. +Für eine vollständige Liste siehe [app.METHOD](/en/5x/api#app.METHOD). + +Es gibt eine spezielle Routing-Methode, `app.all()`, die benutzt wird, um Middleware-Funktionen an einem Pfad für *all* HTTP-Requestmethoden zu laden. Zum Beispiel wird der folgende Handler für Anfragen an die Route `"/secret"` ausgeführt, ob `GET` verwendet wird, `POST`, `PUT`, `DELETE`, oder jede andere HTTP-Anfragemethode, die im [http module]unterstützt wird (https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Zugriff auf den geheimen Abschnitt ...'); + next(); // Kontrolle an den nächsten Handler +}); +``` + +## Routenpfade + +Routenpfade in Kombination mit einer Anfragemethode definieren die Endpunkte, an denen Anfragen gestellt werden können. Routenpfade können Zeichenketten, Zeichenkettenmuster oder reguläre Ausdrücke sein. + + + +Im Ausdruck 5, die Zeichen `? , `+`, `\*`, `[]`und`()\` werden anders behandelt als in Version +4, bitte lesen Sie die [Migrationsanleitung](/en/guide/migrating-5#path-syntax) für weitere Informationen. + + + + + +Im Ausdruck 4 müssen reguläre Ausdrücke wie `$` mit einem `\` maskiert werden. + + + + + +Express verwendet [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) um die Route +Pfade zu treffen; lesen Sie die Dokumentation zu regexp für alle Möglichkeiten bei der Definition von Routenpfaden. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) ist ein praktisches Werkzeug für +grundlegende Express-Routen zu testen, obwohl es kein Muster-Matching unterstützt. + + + +Abfragezeichenketten sind nicht Teil des Routenweges. + +### Routenpfade basierend auf Zeichenketten + +Dieser Routenpfad wird den Anfragen an die Root-Route `/` entsprechen. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +Dieser Routenpfad wird den Anfragen auf `/about` entsprechen. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +Dieser Routenpfad entspricht den Anfragen zu `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Routenpfade basierend auf Stringmustern + + + +Die Zeichenkettenmuster in Express 5 funktionieren nicht mehr. Weitere Informationen finden Sie in der Migration +Anleitung . + + + +Dieser Routenpfad stimmt mit `acd` und `abcd` überein. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +Dieser Routenpfad stimmt mit `abcd`, `abbcd`, `abbbcd` usw. überein. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +Dieser Routenpfad stimmt mit `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd` usw. überein. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +Dieser Routenpfad stimmt mit `/abe` und `/abcde` überein. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Routenpfade basierend auf regulären Ausdrücken + +Dieser Routenpfad stimmt mit einem "a" darin überein. + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +Dieser Routenpfad stimmt mit 'butterfly' und 'Drachenfly' überein, aber nicht mit 'butterflyman', 'Drachenflyman' und so weiter. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Routenparameter + +Routenparameter sind URL-Segmente, die zur Erfassung der an ihrer Position in der URL angegebenen Werte verwendet werden. Die erfassten Werte werden im Objekt `req.params` gefüllt, wobei der Name des im Pfad angegebenen Routenparameter als ihre jeweiligen Schlüssel angegeben ist. + +``` +Routenpfad: /users/:userId/books/:bookId +Anfrage-URL: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +Um Routen mit Routenparametern zu definieren, geben Sie einfach die Routenparameter im Pfad der Route, wie unten gezeigt, an. + +```js +app.get('/users/:userId/bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +Der Name der Routenparameter muss aus "Wortzeichen" ([A-Za-z0-9_] ) bestehen. + + + +Da die Bindestriche (`-`) und der Punkt (`.`) wörtlich interpretiert werden, können sie zusammen mit Routenparametern für nützliche Zwecke verwendet werden. + +``` +Routenpfad: /flights/:from-:to +Abfrage URL: http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Routenpfad: /plantae/:genus.:species +Anfrage URL: http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +In express 5, Regexp characters are not supported in route paths, for more information please +refer to the [migration guide](/en/guide/migrating-5#path-syntax). + + + +Um mehr Kontrolle über den exakten String zu haben, der mit einem Route-Parameter übereinstimmen kann, können Sie einen regulären Ausdruck in Klammern (`()`) anhängen: + +``` +Routenpfad: /user/:userId(\d+) +Anfrage-URL: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Weil der reguläre Ausdruck in der Regel Teil einer literalen Zeichenkette ist, Stellen Sie sicher, dass Sie `\` +Zeichen mit einem zusätzlichen Backslash maskieren, zum Beispiel `\d+`. + + + + +In Express 4.x wird das `*` Zeichen in regulären Ausdrücken nicht auf die übliche Weise interpretiert. Benutze `{0,}` anstelle von `*`. Dies wird wahrscheinlich in Express 5 behoben. + + +## Routenhandler + +Du kannst mehrere Callback-Funktionen bereitstellen, die sich wie [middleware](/en/guide/using-middleware) verhalten um eine Anfrage zu bearbeiten. Die einzige Ausnahme ist, dass diese Callbacks `next('route')` aufrufen könnten, um die restlichen Rufnummern zu umgehen. Sie können diesen Mechanismus nutzen, um Vorbedingungen auf einer Route aufzuerlegen, dann die Kontrolle an die nachfolgenden Routen übergeben, wenn es keinen Grund gibt, mit der aktuellen Route fortzufahren. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params. d === '0') { + return next('route'); + } + res. end(`User ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Special handler for user ID 0'); +}); +``` + +In diesem Beispiel: + +* `GET /user/5` → behandelt durch die erste Route → sendet "Benutzer 5" +* `GET /user/0` → erste Routenaufrufe `next('route')`, überspringt zur nächsten passenden `/user/:id` Route + +Routenhandler können in Form einer Funktion, eines Arrays von Funktionen oder Kombinationen beider sein, wie in den folgenden Beispielen gezeigt. + +Eine einzelne Callback-Funktion kann eine Route handhaben. Zum Beispiel: + +```js +app.get('/example/a', (req, res) => { + res.send('Hallo von A!'); +}); +``` + +Mehr als eine Callback-Funktion kann eine Route handhaben (stelle sicher, dass du das `next` Objekt angibst). Zum Beispiel: + +```js +app.get( + '/example/b', + (req, res, next) => { + Konsole. og('die Antwort wird von der nächsten Funktion gesendet. .'); + next(); + }, + (req, res) => { + res. end('Hallo von B!'); + } +); +``` + +Ein Array von Callback-Funktionen kann eine Route handhaben. Zum Beispiel: + +```js +const cb0 = function (req, res, next) { + Konsole. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +const cb2 = function (req, res) { + res. end('Hallo von C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +Eine Kombination aus unabhängigen Funktionen und Arrays von Funktionen kann eine Route handhaben. Zum Beispiel: + +```js +const cb0 = function (req, res, next) { + Konsole. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +App. et( + '/example/d', + [cb0, cb1], + (req, res, next) => { + Konsole. og('die Antwort wird von der nächsten Funktion gesendet. .'); + next(); + }, + (req, res) => { + res. end('Hallo von D!'); + } +); +``` + +## Antwortmethoden + +Die Methoden auf dem Antwortobjekt (`res`) in der folgenden Tabelle können eine Antwort an den Client senden und den Request-Antwort-Zyklus beenden. Wenn keine dieser Methoden von einem Routenhandler aufgerufen wird, bleibt die Client-Anfrage hängen. + +| Methode | Beschreibung | +| --------------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | Fordern Sie eine Datei zum Download an. | +| [res.end()](/en/5x/api#res.end) | Beenden Sie den Antwort-Prozess. | +| [res.json()](/en/5x/api#res.json) | Sende eine JSON-Antwort. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Senden Sie eine JSON-Antwort mit JSONP-Unterstützung. | +| [res.redirect()](/en/5x/api#res.redirect) | Anfrage umleiten. | +| [res.render()](/en/5x/api#res.render) | Ansichtsvorlage ausblenden. | +| [res.send()](/en/5x/api#res.send) | Senden Sie eine Antwort von verschiedenen Typen. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Senden Sie eine Datei als octet-Stream. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Legen Sie den Antwort-Statuscode fest und senden Sie seine Zeichenfolge Repräsentation als Antwortkörper. | + +## app.route() + +Sie können verkettende Routenhandler für einen Routenpfad erstellen, indem Sie `app.route()` verwenden. +Da der Weg an einem einzigen Ort angegeben wird, ist die Schaffung modularer Routen hilfreich, ebenso wie die Reduzierung von Redundanz und Typos. Weitere Informationen über Routen finden Sie unter [Router() documentation](/en/5x/api#router). + +Hier ist ein Beispiel für verkettete Routenhandler, die mit `app.route()` definiert werden. + +```js +app + .route('/book') + .get((req, res) => { + res. end('Holt ein zufälliges Buch'); + }) + . ost(req, res) => { + res.send('Add a book'); + }) + . ut((req, res) => { + res.send('Buch aktualisieren'); +}); +``` + +## express.Router + +Verwende die Klasse `express.Router`, um modulare mountbare Routenhandler zu erstellen. Eine `Router`-Instanz ist ein komplettes Middleware- und Routing-System; aus diesem Grund wird sie oft als "Mini-App" bezeichnet. + +Das folgende Beispiel erzeugt einen Router als Modul, lädt eine Middleware-Funktion darin definiert einige Routen und mountet das Router-Modul auf einem Pfad in der Hauptanwendung. + +Erstelle eine Router-Datei namens `birds.js` im App-Verzeichnis, mit folgendem Inhalt: + +```js +const express = require('express'); +const Router = express. outer(); + +// Middleware, die spezifisch für diesen Router +const timeLog = (req, res, next) => { + Konsole ist. og('Zeit: ', Date.now()); + next(); +}; +Router. se(timeLog); + +// die Startseite Route +router.get('/', (req, res) => { + res. end('Birds home page'); +}); +// die "about route +definieren. et('/about', (req, res) => { + res.send('Über Vögel'); +}); + +module.exports = router; +``` + +Laden Sie dann das Router-Modul in der App: + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', Vögel); +``` + +Die App wird nun in der Lage sein, Anfragen an `/birds` und `/birds/about` zu bearbeiten, aufrufen sowie die Middleware-Funktion `timeLog` aufrufen, die spezifisch für die Route ist. + +Aber wenn die übergeordnete Route `/birds` Pfadparameter hat, wird sie standardmäßig nicht von den Unterrouten aus erreichbar sein. Um es zugänglich zu machen, müssen Sie die Option "mergeParams" an den Router-Konstruktor [reference](/en/5x/api#app.use) übergeben. + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/de/5x/guide/using-middleware.mdx b/src/content/docs/de/5x/guide/using-middleware.mdx new file mode 100644 index 0000000000..667105556e --- /dev/null +++ b/src/content/docs/de/5x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Middleware verwenden +description: Lernen Sie, wie Sie Middleware in Express.js-Anwendungen verwenden, einschließlich Middleware auf Anwendungsebene und Routerebene, Fehlerbehandlung und Integration von Middleware. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express ist ein Routing- und Middleware-Webframework mit minimaler Funktionalität: Eine Express-Anwendung ist im Wesentlichen eine Reihe von Middleware-Funktionsaufrufen. + +*Middleware* Funktionen sind Funktionen, die Zugriff auf das [request object](/en/5x/api#req) (`req`), das [Antwort-Objekt](/en/5x/api#res) (`res`) und die nächste Middleware-Funktion im Request-Antwort-Zyklus der Anwendung. Die nächste Middleware-Funktion wird üblicherweise durch eine Variable namens `next` bezeichnet. + +Middleware-Funktionen können folgende Aufgaben ausführen: + +* Führe jeden Code aus. +* Änderungen an der Anfrage und den Antwort-Objekten vornehmen. +* Beende den Request-Antwort-Zyklus. +* Rufen Sie die nächste Middleware-Funktion im Stack auf. + +Wenn die aktuelle Middleware-Funktion den Request-Antwort-Zyklus nicht beendet, muss sie `next()` aufrufen, um die Kontrolle an die nächste Middleware-Funktion zu übergeben. Andernfalls bleibt die Anfrage hängen. + +Eine Express-Anwendung kann folgende Arten von Middleware verwenden: + +* [Middleware](#middleware.application) +* [Router-Level-Middleware](#middleware.router) +* [Error-handling middleware](#middleware.error-handling) +* [Integrierte Middleware](#middleware.built-in) +* [Middleware von Drittanbietern](#middleware.third-party) + +Sie können Middleware auf Anwendungsebene und Routerebene mit einem optionalen Mount-Pfad laden. +Sie können auch eine Reihe von Middleware-Funktionen zusammen laden, die einen Sub-Stack des Middleware-Systems an einem Mount-Punkt erzeugen. + +## Middleware auf Anwendungsebene + +Binde Middleware auf Anwendungsebene an eine Instanz des [app object](/en/5x/api#app) durch Verwendung der `app.use()` und `app. ETHOD()` Funktionen, wobei `METHOD` die HTTP-Methode der Anfrage ist, die die Middleware-Funktion in Kleinbuchstaben behandelt (wie GET, PUT, oder POST) + +Dieses Beispiel zeigt eine Middleware-Funktion ohne Mount-Pfad. Die Funktion wird jedes Mal ausgeführt, wenn die App eine Anfrage erhält. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +Dieses Beispiel zeigt eine Middleware-Funktion, die auf dem `/user/:id` Pfad eingehängt ist. Die Funktion wird für jede Art von +HTTP-Anfrage im `/user/:id` Pfad ausgeführt. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +Dieses Beispiel zeigt eine Route und deren Handler-Funktion (Middleware-System). Die Funktion bearbeitet GET-Anfragen an den Pfad `/user/:id`. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +Hier ist ein Beispiel für das Laden einer Reihe von Middleware-Funktionen an einem Mount-Punkt, mit einem Mount-Pfad. +Es illustriert einen Middleware-Unterstapel, der Anfrageinformationen für jede Art von HTTP-Anfrage in den Pfad `/user/:id` ausgibt. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + console. og('Request Type:', req.method); + next(); + } +); +``` + +Routenhandler ermöglichen es Ihnen, mehrere Routen für einen Pfad zu definieren. Das folgende Beispiel definiert zwei Routen für GET-Anfragen zum Pfad `/user/:id`. Die zweite Route wird keine Probleme verursachen, aber sie wird nie aufgerufen, weil die erste Route den Request-Antwort-Zyklus beendet. + +Dieses Beispiel zeigt einen Middleware-Sub-Stack an, der GET-Anfragen im `/user/:id`-Pfad behandelt. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req. arams.id); + next(); + }, + (req, res, next) => { + res. end('User Info'); + } +); + +// Handler für den /user/:id Pfad, der die Benutzer-ID +App ausgibt. et('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +Um die restlichen Middleware-Funktionen eines Routers Middleware-Stacks zu überspringen, rufen Sie `next('route')` auf, um die Kontrolle an die nächste Route zu übergeben. + + + +`next('route')` funktioniert nur in Middleware-Funktionen, die mit den Funktionen +`app.METHOD()` oder `router.METHOD()` geladen wurden. + + + +Dieses Beispiel zeigt einen Middleware-Sub-Stack an, der GET-Anfragen im `/user/:id`-Pfad behandelt. + +```js +app.get( + '/user/:id', + (req, res, Nächste) => { + // wenn die Benutzer-ID 0 ist springe zur nächsten Route + wenn (req. arams. d === '0') als nächstes ('route'); + // Andernfalls übergeben Sie die Steuerung an die nächste Middleware-Funktion in diesem Stack + else next(); + }, + (req, res, next) => { + // Senden Sie eine reguläre Antwort + res. end('regular'); + } +); + +// Handler für den /user/:id Pfad, der eine spezielle Antwort +App sendet. et('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +Middleware kann auch in einem Array für Wiederverwendbarkeit deklariert werden. + +Dieses Beispiel zeigt ein Array mit einem Middleware-Sub-Stack an, das GET-Anfragen im Pfad `/user/:id` behandelt + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req. riginalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Request Type:', req. ethod); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +App. et('/user/:id', logStuff, (req, res, next) => { + res.send('User Info'); +}); +``` + +## Middleware auf Routerebene + +Middleware auf Router-Ebene funktioniert wie Middleware auf Anwendungsebene, es sei denn, es ist an eine Instanz von `express.Router()` gebunden. + +```js +const router = express.Router(); +``` + +Laden Sie die Middleware router-level mittels der Funktionen `router.use()` und `router.METHOD()`. + +Der folgende Beispielcode repliziert das oben angezeigte Middleware-System für Middleware auf Anwendungsebene: + +```js +const express = require('express'); +const app = express(); +const router = express. Externe(); + +// eine Middleware-Funktion ohne Mount-Pfad. Dieser Code wird für jede Anfrage an den Router +ausgeführt. se(req, res, next) => { + console.log('Zeit:', Datum. ow()); + next(); +}); + +// Ein Middleware-Sub-Stack zeigt Anfrageinformationen für jede Art von HTTP-Anfrage an den /user/:id path +Router an. se( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + Konsole. og('Request Typ:', req. ethod); + next(); + } +); + +// ein Middleware-Sub-Stack, der GET-Anfragen an den /user/:id path +Router verarbeitet. et( + '/user/:id', + (req, res, Nächste) => { + // wenn die Benutzer-ID 0 ist springe zum nächsten Router + wenn (req. arams. d === '0') als nächstes ('route'); + // Andernfalls übergeben Sie die Kontrolle an die nächste Middleware-Funktion in diesem Stapel + else next(); + }, + (req, res, next) => { + // rendern Sie eine reguläre Seite + res. ender('regular'); + } +); + +// Handler für den /user/:id Pfad, der eine spezielle Seite +Router darstellt. et('/user/:id', (req, res, next) => { + Konsole. og(req.params.id); + res.render('special'); +}); + +// Router auf die App +app.use('/', Router); +``` + +To skip the rest of the router's middleware functions, call `next('router')` +to pass control back out of the router instance. + +Dieses Beispiel zeigt einen Middleware-Sub-Stack an, der GET-Anfragen im `/user/:id`-Pfad behandelt. + +```js +const express = require('express'); +const app = express(); +const router = express. Externe (); + +// Vorhersage des Routers mit Scheck und Kaution bei Bedarf +Router. se((req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router. et('/user/:id', (req, res) => { + res.send('hallo, user!'); +}); + +// den Router verwenden und 401 alles, was durch die +App fällt. se('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## Fehler beim Umgang mit Middleware + + + +Bei der Fehlerbehebung der Middleware werden immer *vier* Argumente verwendet. Sie müssen vier Argumente angeben, um +als Middleware-Funktion zu identifizieren. Selbst wenn du das `next` +Objekt nicht verwenden musst, musst du es angeben, um die Signatur zu pflegen. Andernfalls wird das `next` Objekt +als reguläre Middleware interpretiert und wird Fehler nicht bearbeiten. + + + +Definieren Sie die Middleware-Funktionen wie andere Middleware-Funktionen außer mit vier Argumenten anstelle von drei, speziell mit der Signatur `(err, req, res, next)`: + +```js +app.use(((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Etwas kaputt!'); +}); +``` + +Details über die Fehlerbehandlungsmittelsoftware finden Sie hier: [Fehlerbehandlung](/en/guide/error-handling). + +## Integrierte Middleware + +Ab Version 4.x ist Express nicht mehr abhängig von [Connect](https://github.com/senchalabs/connect). Die Middleware- +\-Funktionen, die zuvor mit Express integriert wurden, befinden sich nun in separaten Modulen; siehe [Liste der Middleware-Funktionen](https://github.com/senchalabs/connect#middleware). + +Express hat die folgenden integrierten Middleware-Funktionen: + +* [express.static](/en/5x/api#express.static) dient statischen Assets wie HTML-Dateien, Bilder und so weiter. +* [express.json](/en/5x/api#express.json) analysiert eingehende Anfragen mit JSON Payloads. **HINWEIS: Verfügbar mit Express 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) analysiert eingehende Anfragen mit URL-kodierten Payloads. **HINWEIS: Verfügbar mit Express 4.16.0+** + +## Drittanbieter-Middleware + +Verwenden Sie Middleware von Drittanbietern, um Funktionen zu Express-Apps hinzuzufügen. + +Installieren Sie das Modul Node.js für die erforderliche Funktionalität, laden Sie es dann in Ihrer App auf der Anwendungsebene oder auf der Routerebene. + +Das folgende Beispiel zeigt die Installation und das Laden der Cookie-Parsing-Middleware-Funktion "cookie-parser". + +```bash +$ npm Cookie-Parser installieren +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// cookie-parsing middleware +app.use(cookieParser()); +``` + +Für eine partielle Liste der Middleware-Funktionen von Drittanbietern, die häufig mit Express verwendet werden, siehe: [Middleware](../resources/middleware). diff --git a/src/content/docs/de/5x/guide/using-template-engines.mdx b/src/content/docs/de/5x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..8fddcf43be --- /dev/null +++ b/src/content/docs/de/5x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Template-Engines mit Express verwenden +description: Entdecken Sie, wie Sie Template-Engines wie Pug, Handlebars und EJS mit Express.js integrieren und nutzen können, um dynamische HTML-Seiten effizient zu machen. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Eine *template engine* ermöglicht es Ihnen, statische Template-Dateien in Ihrer Anwendung zu verwenden. Zur Laufzeit ersetzt die Template-Engine +Variablen in einer Template-Datei mit aktuellen Werten und verwandelt die Vorlage in eine HTML-Datei, die an den Client gesendet wird. +Dieser Ansatz erleichtert die Gestaltung einer HTML-Seite. + +Der [Express-Anwendungsgenerator](/en/starter/generator) verwendet [Pug](https://pugjs.org/api/getting-started.html) als Standardwert, aber es unterstützt auch [Handlebars](https://www.npmjs.com/package/handlebars), und [EJS](https://www.npmjs.com/package/ejs), unter anderem. + +Um Template-Dateien zu rendern, setzen Sie folgende [Anwendungs-Einstellungen-Eigenschaften](/en/4x/api#app.set), in der Standardeinstellung `app.js`, die vom Generator erstellt wurde: + +* `views`, das Verzeichnis, in dem sich die Template-Dateien befinden. Eg: `app.set('views', './views')`. + Dies ist standardmäßig im Verzeichnis `views` im Root-Verzeichnis der Anwendung. +* `view engine`, die zu verwendende Template-Engine. Um zum Beispiel die Mückenvorlagen-Engine zu verwenden: `app.set('view engine', 'pug')`. + +Installieren Sie dann das entsprechende Template Engine npm Paket; zum Beispiel um Pug: + +```bash +$ npm Installations-Pug --save +``` + + +Express-konforme Template-Engines wie MUG exportieren eine Funktion namens `__express(filePath, options, callback)`, +welche `res.render()` aufruft, um den Template-Code zu rendern. + +Einige Template-Engines folgen nicht dieser Konvention. Die [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +Bibliothek folgt dieser Konvention, indem sie alle populären Template-Engines von Node.js abbildet, und arbeitet daher nahtlos in Express. + + + +Nachdem die View Engine gesetzt ist, müssen Sie nicht die Engine angeben oder das Template Engine Modul in Ihrer App laden; +Express lädt das Modul intern, zum Beispiel: + +```js +app.set('view engine', 'pug'); +``` + +Erstelle dann eine Pug Template Datei namens `index.pug` im `views` Verzeichnis mit folgendem Inhalt: + +```pug +html + Kopf + title= title + Körper + h1= Nachricht +``` + +Erstelle eine Route um die `index.pug` Datei zu rendern. Wenn die `view engine` Eigenschaft nicht gesetzt ist, +musst du die Erweiterung der `view` Datei angeben. Andernfalls können Sie es auslassen. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hallo there!' }); +}); +``` + +Wenn du eine Anfrage an die Startseite stellt, wird die `index.pug` Datei als HTML dargestellt. + +Der View Engine-Cache speichert nicht den Inhalt der Templateausgabe, sondern nur die zugrunde liegende Vorlage selbst. Die Ansicht wird noch mit jeder Anfrage neu gerendert, auch wenn der Cache eingeschaltet ist. diff --git a/src/content/docs/de/5x/guide/writing-middleware.mdx b/src/content/docs/de/5x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..984cc71804 --- /dev/null +++ b/src/content/docs/de/5x/guide/writing-middleware.mdx @@ -0,0 +1,209 @@ +--- +title: Schreibe Middleware für die Verwendung in Express-Apps +description: Erfahren Sie, wie Sie benutzerdefinierte Middleware-Funktionen für Express.js-Anwendungen schreiben, einschließlich Beispielen und Best Practices zur Verbesserung der Request- und Response-Behandlung. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Middleware* Funktionen sind Funktionen, die Zugriff auf das [request object](/en/5x/api#req) (`req`), die [Antwort-Objekt](/en/5x/api#res) (`res`) und die `next` Funktion im Request-Antwort-Zyklus der Anwendung. Die `next`-Funktion ist eine Funktion im Express-Router, der beim Aufruf die Middleware ausführt, die die aktuelle Middleware abfolgt. + +Middleware-Funktionen können folgende Aufgaben ausführen: + +* Führe jeden Code aus. +* Änderungen an der Anfrage und den Antwort-Objekten vornehmen. +* Beende den Request-Antwort-Zyklus. +* Rufen Sie die nächste Middleware im Stapel auf. + +Wenn die aktuelle Middleware-Funktion den Request-Antwort-Zyklus nicht beendet, muss sie `next()` aufrufen, um die Kontrolle an die nächste Middleware-Funktion zu übergeben. Andernfalls bleibt die Anfrage hängen. + +Die folgende Abbildung zeigt die Elemente eines Middleware-Funktionsaufrufs: + +![Elemente einer Middleware-Funktion aufruf](/images/express-mw.png) + +Beginnend mit Express 5 ruft Middleware-Funktionen, die ein Versprechen zurückgeben, `next(value)` auf, wenn sie einen Fehler ablehnen oder werfen. `next` wird entweder mit dem abgelehnten Wert oder mit dem Wurffehler aufgerufen. + +## Beispiel + +Hier ist ein Beispiel für eine einfache "Hallo World"-Express-Anwendung. +Der Rest dieses Artikels definiert und fügt der Anwendung drei Middleware-Funktionen hinzu: +eine mit dem Namen `myLogger`, die eine einfache Logmeldung ausgibt, einen namens `requestTime`, der +den Zeitstempel der HTTP-Anfrage anzeigt und einen, der `validateCookies` genannt wird, der eingehende Cookies validiert. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hallo World!'); +}); + +app.listen(3000); +``` + +### Middleware-Funktion myLogger + +Hier ist ein einfaches Beispiel für eine Middleware-Funktion namens "myLogger". Diese Funktion druckt nur +"LOGGED", wenn eine Anfrage an die App durchläuft. Die Middleware-Funktion wird einer +Variable mit dem Namen `myLogger` zugewiesen. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +Beachten Sie den obigen Aufruf zu `next()`. Beim Aufruf dieser Funktion wird die nächste Middleware-Funktion in +der App aufgerufen. Die `next()` Funktion ist kein Teil des Knotens. s oder Express API, aber ist das dritte +\-Argument, das an die Middleware-Funktion übergeben wird. Die `next()` Funktion kann alles benannt werden, +, aber nach der Konvention wird sie immer als "weiter" bezeichnet. Um Verwirrung zu vermeiden, verwenden Sie immer dieses Übereinkommen. + + + +Um die Middleware-Funktion zu laden, rufen Sie `app.use()` auf, indem Sie die Middleware-Funktion angeben. +Zum Beispiel lädt der folgende Code die `myLogger` Middleware-Funktion vor der Route zum Root-Pfad (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console. og('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Hallo World!'); +}); + +app.listen(3000); +``` + +Jedes Mal, wenn die App eine Anfrage erhält, gibt sie die Nachricht "LOGGED" auf das Terminal aus. + +Die Reihenfolge des Laden von Middleware ist wichtig: Middleware-Funktionen, die zuerst geladen werden, werden auch zuerst ausgeführt. + +Wenn `myLogger` nach der Route zum Wurzelpfad geladen wird, erreicht die Anfrage nie und die App druckt nicht "LOGGED", da der Route-Handler des Root-Pfades den Request-Antwort-Zyklus beendet. + +Die Middleware-Funktion `myLogger` druckt einfach eine Nachricht, übergibt dann die Anfrage an die nächste Middleware-Funktion im Stack durch Aufruf der `next()` Funktion. + +### Middleware-Funktionsanfragezeit + +Als nächstes erstellen wir eine Middleware-Funktion namens "requestTime" und fügen eine Eigenschaft namens `requestTime` +dem Anfrageobjekt hinzu. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +Die App verwendet nun die „requestTime“-Middleware-Funktion. Auch die Callback-Funktion der Root-Pfadroute verwendet die Eigenschaft, die die Middleware-Funktion zu `req` hinzufügt (das Anfrageobjekt). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app.get('/', (req, res) => { + let responseText = 'Hello World!
'; + responseText += `Requested at: ${req.requestTime}`; + res.send(responseText); +}); + +app.listen(3000); +``` + +Wenn Sie eine Anfrage an das Stammverzeichnis der App stellen, zeigt die App nun den Zeitstempel Ihrer Anfrage im Browser an. + +### Middleware-Funktion validateCookies + +Schließlich erstellen wir eine Middleware-Funktion, die eingehende Cookies validiert und eine 400 Antwort schickt, wenn Cookies ungültig sind. + +Hier ist eine Beispielfunktion, die Cookies mit einem externen Asynchrondienst überprüft. + +```js +async function cookieValidator(cookies) { + try { + wait externallyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Ungültige Cookies'); + } +} +``` + +Hier verwenden wir die [`cookie-parser`](/en/resources/middleware/cookie-parser) Middleware, um eingehende Cookies vom `req` Objekt zu analysieren und sie an unsere `cookieValidator` Funktion zu übergeben. Die `validateCookies` Middleware gibt ein Versprechen zurück, das bei Ablehnung automatisch unseren Fehlerhandler auslöst. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('. cookieValidator'); + +const app = express(); + +async function validateCookies(req, res, next) { + wartet cookieValidator(req. ookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// Fehlerbehandler +app. se(err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Beachte, wie `next()` nach `wait cookieValidator(req.cookies)` aufgerufen wird. Dies stellt sicher, dass, wenn +`cookieValidator` auflöst, die nächste Middleware im Stack aufgerufen wird. Wenn du etwas +an die `next()` Funktion übergibt (außer den String `'route'` oder `'router'`), Express betrachtet die aktuelle +Anfrage als Fehler und überspringt alle verbleibenden Funktionen zur Fehlerbehandlung und Middleware +. + + + +Weil Sie Zugriff auf das Anfrageobjekt, das Antwortobjekt, die nächste Middleware-Funktion im Stapel und den gesamten Knoten haben. s API, die Möglichkeiten mit Middleware-Funktionen sind endlos. + +Für weitere Informationen über Express Middleware siehe: [Express Middleware](/en/guide/using-middleware). + +## Konfigurierbare Middleware + +Wenn Sie Ihre Middleware konfigurieren müssen, exportieren Sie eine Funktion, die ein Optionsobjekt oder andere Parameter akzeptiert, , die dann die Middleware-Implementierung basierend auf den Eingabeparametern zurückgibt. + +Datei: `my-middleware.js` + +```js +modul. xports = function (options) { + return function (req, res, next) { + // Implementierung der Middleware-Funktion basierend auf dem Options-Objekt + next(); + }; +}; +``` + +Die Middleware kann nun wie unten gezeigt verwendet werden. + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Siehe [cookie-session](https://github.com/expressjs/cookie-session) und [compression](https://github.com/expressjs/compression) für Beispiele konfigurierbarer Middleware. diff --git a/src/content/docs/de/5x/starter/basic-routing.mdx b/src/content/docs/de/5x/starter/basic-routing.mdx new file mode 100644 index 0000000000..3b2a6d130d --- /dev/null +++ b/src/content/docs/de/5x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Basisrouting +description: Lernen Sie die Grundlagen des Routings in Express.js Anwendungen kennen, wie Sie Routen definieren, HTTP-Methoden handhaben und Routenhandler für Ihren Webserver erstellen. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* bezieht sich darauf, wie eine Anwendung auf einen bestimmten Endpunkt antwortet , die eine URI (oder Pfad) und eine bestimmte HTTP-Request-Methode (GET, POST usw.) ist. + +Jede Route kann eine oder mehrere Handler-Funktionen haben, die ausgeführt werden, wenn die Route übereinstimmt. + +Die Routendefinition nimmt folgende Struktur ein: + +```js +app.METHOD(PATH, HANDLER); +``` + +Wo: + +* `app` ist eine Instanz von `express `. +* `METHOD` ist eine [HTTP-Anfrage-Methode](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in Kleinbuchstaben. +* `PATH` ist ein Pfad auf dem Server. +* `HANDLER` ist die Funktion, die ausgeführt wird, wenn die Route übereinstimmt. + + + +Dieses Tutorial setzt voraus, dass eine Instanz von `express ` namens `app` erstellt wird und der Server +läuft. Wenn du nicht vertraut bist, eine App zu erstellen und sie zu starten, schau dir das Hallo Welt +Beispiel. + + + +Die folgenden Beispiele veranschaulichen die Definition einfacher Routen. + +Antworte mit `Hallo World!` auf der Homepage: + +```js +app.get('/', (req, res) => { + res.send('Hallo Welt!'); +}); +``` + +Antwort auf eine POST-Anfrage auf der Root-Route (`/`), der Startseite der Anwendung: + +```js +app.post('/', (req, res) => { + res.send('Hat eine POST-Anfrage'); +}); +``` + +Antworte auf eine PUT-Anfrage auf die `/user`-Route: + +```js +app.put('/user', (req, res) => { + res.send('Eine PUT-Anfrage bei /user'); +}); +``` + +Antworte auf eine LÖSCHE Anfrage auf die `/user`-Route: + +```js +app.delete('/user', (req, res) => { + res.send('Erhalte eine DELETE Anfrage unter /user'); +}); +``` + +Weitere Details zum Routen finden Sie im [Routing Guide](/en/guide/routing). diff --git a/src/content/docs/de/5x/starter/examples.mdx b/src/content/docs/de/5x/starter/examples.mdx new file mode 100644 index 0000000000..82f5980728 --- /dev/null +++ b/src/content/docs/de/5x/starter/examples.mdx @@ -0,0 +1,49 @@ +--- +title: Express-Beispiele +description: Entdecken Sie eine Sammlung von Express.js Anwendungsbeispielen, die verschiedene Anwendungsfälle, Integrationen und erweiterte Konfigurationen umfassen, um Ihnen zu helfen Ihre Projekte zu erlernen und zu bauen. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Diese Seite enthält eine Liste von Beispielen mit Express. + +* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Authentifizierung mit Login und Passwort +* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - HTTP-Inhaltsaushandlung +* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Arbeiten mit Cookie-basierten Sitzungen +* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Arbeiten mit Cookies +* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Übertragung von Dateien zum Client +* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Arbeiten mit eingebetteten JavaScript-Vorlagen (ejs) +* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Fehlerseiten erstellen +* [error](https://github.com/expressjs/express/tree/master/examples/error) - Mit Fehler-Middleware arbeiten +* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Einfacher Anfragehandler +* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown als Template-Engine +* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Mit mehreren Express-Routern arbeiten +* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - Controller im MVC-Stil +* [online](https://github.com/expressjs/express/tree/master/examples/online) - Verfolgung der Online-Benutzeraktivität mit `online` und `redis` Paketen +* [params](https://github.com/expressjs/express/tree/master/examples/params) - Arbeiten mit Routenparametern +* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Mehrere HTTP-Operationen auf derselben Ressource +* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Routen mit einer Karte organisieren +* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Mit Route Middleware arbeiten +* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Routen pro Ressource organisieren +* [search](https://github.com/expressjs/express/tree/master/examples/search) - Such-API +* [session](https://github.com/expressjs/express/tree/master/examples/session) - Benutzersitzungen +* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Serviere statische Dateien +* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Arbeiten mit virtuellen Hosts +* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Ansichten dynamisch rendern +* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Speichern von Daten im Anfrageobjekt zwischen Middleware-Aufrufen +* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Einfacher API-Dienst + +## Zusätzliche Beispiele + +Dies sind einige zusätzliche Beispiele mit umfassenderen Integrationen. + + + +Diese Informationen beziehen sich auf Sites, Produkte oder Module, die nicht vom +Expressjs Team betreut werden. Die Auflistung hier stellt keine Billigung oder Empfehlung des Projektteams von +Expressjs dar. + + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Vollstack App mit Express und Next.js mit [Prisma](https://www.npmjs.com/package/prisma) als ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API mit Express in TypeScript mit [Prisma](https://www.npmjs.com/package/prisma) als ORM diff --git a/src/content/docs/de/5x/starter/faq.md b/src/content/docs/de/5x/starter/faq.md new file mode 100644 index 0000000000..8df0cc1a28 --- /dev/null +++ b/src/content/docs/de/5x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: FAQ +description: Finden Sie Antworten auf häufig gestellte Fragen zu Express.js, darunter Themen wie Anwendungsstruktur, Modelle, Authentifizierung, Template-Engines, Fehlerbehandlung und mehr. +--- + +## Wie kann ich meine Anwendung strukturieren? + +Auf diese Frage gibt es keine endgültige Antwort. Die Antwort hängt von +vom Umfang Ihrer Anwendung und dem beteiligten Team ab. Um so flexibel wie möglich +zu sein, macht Express keine Annahmen in Bezug auf die Struktur. + +Routen und andere anwendungsspezifische Logik können in beliebig vielen Dateien +in beliebiger Verzeichnisstruktur gespeichert werden. Folgende +Beispiele für Inspirationen anzeigen: + +- [Route Listings](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Routenplane](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Außerdem gibt es Erweiterungen von Drittanbietern für Express, die einige dieser Muster vereinfachen: + +- [Ressourcenreiches Routen](https://github.com/expressjs/express-resource) + +## Wie definiere ich Modelle? + +Express hat keine Vorstellung von Datenbanken. Dieses Konzept ist +bis zu Drittanbieter-Knotenmodulen übrig und erlaubt Ihnen eine +Schnittstelle mit fast jeder Datenbank. + +Siehe [LoopBack](http://loopback.io) für ein Express-basiertes Framework, das um Modelle zentriert ist. + +## Wie kann ich Benutzer authentifizieren? + +Authentifizierung ist ein anderer Bereich, in dem sich Express nicht +wagt. Sie können ein beliebiges Authentifizierungsschema verwenden. +Für ein einfaches Benutzername/Passwort-Schema, siehe [dieses Beispiel](https://github.com/expressjs/express/tree/master/examples/auth). + +## Welche Template-Engines unterstützt Express? + +Express unterstützt jede Template-Engine, die mit der Signatur `(Pfad, locals, callback)` übereinstimmt. +Um die Schnittstellen der Template-Engine und das Caching zu normalisieren, lesen Sie bitte +[consolidate.js](https://github.com/visionmedia/consolidate.js) +Projekt für Unterstützung. Nicht aufgelistete Template-Engines könnten die Express-Signatur trotzdem unterstützen. + +Weitere Informationen finden Sie unter [Template-Engines mit Express](/en/guide/using-template-engines). + +## Wie gehe ich mit 404 Antworten um? + +In Express sind 404 Antworten nicht das Ergebnis eines Fehlers, daher wird die Middleware von +nicht erfasst. Dieses Verhalten ist +, da eine 404-Antwort einfach das Fehlen zusätzlicher Arbeit anzeigt; +in anderen Worten, Express hat alle Middleware-Funktionen und -Routen ausgeführt, +und festgestellt, dass keiner von ihnen reagiert hat. Alles, was Sie +tun müssen, ist eine Middleware-Funktion am unteren Ende des Stacks (unter allen anderen Funktionen) +hinzuzufügen, um eine 404-Antwort zu handhaben: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Fügen Sie Routen dynamisch zur Laufzeit einer Instanz von `express.Router()` +hinzu, so dass die Routen nicht durch eine Middleware-Funktion ersetzt werden. + +## Wie kann ich einen Fehler einrichten? + +Du definierst die Middleware wie andere Middleware, +außer mit vier anstatt drei, spezifisch mit der Signatur `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Weitere Informationen finden Sie unter [Fehlerbehandlung](/en/guide/error-handling). + +## Wie kann ich plain HTML rendern? + +Du bist es nicht! Es gibt keine Notwendigkeit HTML mit der Funktion `res.render()` zu "render". +Wenn du eine bestimmte Datei hast, nutze die Funktion `res.sendFile()`. +Wenn du viele Assets aus einem Verzeichnis lieferst, verwende die `express.static()` +Middleware-Funktion. + +## Welche Version von Node.js benötigt Express? + +- [Express 4.x](/en/4x/api) benötigt Node.js 0.10 oder höher. +- [Express 5.x](/en/5x/api) benötigt Node.js 18 oder höher. diff --git a/src/content/docs/de/5x/starter/generator.mdx b/src/content/docs/de/5x/starter/generator.mdx new file mode 100644 index 0000000000..4559bace00 --- /dev/null +++ b/src/content/docs/de/5x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Express-Applikationsgenerator +description: Lernen Sie, wie Sie mit dem Express-Anwendungsgenerator-Tool schnell ein Skelett für Ihre Express.js-Anwendungen erstellen, die Einrichtung optimieren und die Konfiguration optimieren. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Verwenden Sie das Applikationsgenerator-Tool, "express-generator", um schnell ein Anwendungsskelett zu erstellen. + +Du kannst den Anwendungsgenerator mit dem Befehl `npx` ausführen (verfügbar in Node.js 8.2.0). + +```bash +$ npx Express-Generator +``` + +Für frühere Node-Versionen installieren Sie den Anwendungsgenerator als globales npm-Paket und starten es dann: + +```bash +$ npm Installation -g Express-Generator +$ express +``` + +Zeige die Befehlsoptionen mit der `-h` Option: + +```bash +$ express -h + + Verwendung: Express [options] [dir] + + Optionen: + + -h, --help Ausgabe-Informationen + --version Ausgabe der Versionsnummer + -e, --ejs add ejs engine support + --hbs add handlebars engine support + --pug add pug engine support + -H, --hogan add hogan. s Engine Unterstützung + --no-view generieren ohne View Engine + -v, --view add view support (ejs|hbs|hjs|jade|pug|twig|vash) (defaults to jade) + -c, --css Fügen Sie Stylesheet Unterstützung (less |stylus|compass|sass) (standardmäßig auf plain css) + --git add . itignore + -f, --force auf nicht leeres Verzeichnis +``` + +Zum Beispiel erstellt das Folgende eine Express-App namens *myapp*. Die App wird in einem Ordner namens *myapp* im aktuellen Arbeitsverzeichnis erstellt und die View Engine wird auf Mops gesetzt: + +```bash +$ express --view=pug myapp + + erstellen : myapp + create : myapp/package.json + create : myapp/app. s + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index. s + erstellen : myapp/routes/users. s + create : myapp/public/stylesheets + create : myapp/public/stylesheets/style. ss + erstellen : myapp/views + erstellen : myapp/views/index. ug + erstellen : myapp/views/layout.pug + erstellen : myapp/views/error. ug + erstellen : myapp/bin + erstellen : myapp/bin/www +``` + +Installieren Sie dann Abhängigkeiten: + +```bash +$ cd myapp +$ npm Installation +``` + +Führen Sie auf MacOS oder Linux die App mit diesem Befehl aus: + +```bash +$ DEBUG=myapp:* npm Start +``` + +Benutzen Sie auf Windows Befehlsaufforderung folgenden Befehl: + +```bash +> DEBUG=myapp:* & npm Start setzen +``` + +Verwenden Sie unter Windows PowerShell, diesen Befehl: + +```bash +PS> $env:DEBUG='myapp:*'; npm Start +``` + +Lade dann `http://localhost:3000/` in deinem Browser, um auf die App zuzugreifen. + +Die generierte App hat folgende Verzeichnisstruktur: + +```bash +. + 本 app.js + 本 bin + www + 本 Paket. son + 文 public + Bilder + javascripts + Stylesheets + style. ss + 本 routet + index.js + Benutzer. s + 本 Ansichten + Fehler. ug + 本 index.pug + layout.pug + +7 Verzeichnisse, 9 Dateien +``` + + + +Die vom Generator erstellte App-Struktur ist nur eine von vielen Möglichkeiten, Express-Apps zu strukturieren. +Fühlen Sie sich frei, diese Struktur zu verwenden oder sie so zu modifizieren, dass sie Ihren Bedürfnissen am besten entspricht. + + diff --git a/src/content/docs/de/5x/starter/hello-world.mdx b/src/content/docs/de/5x/starter/hello-world.mdx new file mode 100644 index 0000000000..12f7b3f36c --- /dev/null +++ b/src/content/docs/de/5x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Hallo Weltbeispiel +description: Beginnen Sie mit Express.js, indem Sie eine einfache 'Hallo World'-Anwendung erstellen, die die Grundeinstellung und die Servererstellung für Anfänger demonstriert. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Eingebettet unten ist im Wesentlichen die einfachste Express-App, die Sie erstellen können. Es ist eine einzelne Datei-App +— *not* was Sie bekommen würden, wenn Sie den [Express-Generator](/en/starter/generator), welche +das Gerüst für eine vollständige Anwendung mit zahlreichen JavaScript-Dateien, Jade-Vorlagen und +Unterverzeichnissen für verschiedene Zwecke erstellt. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res. end('Hallo World!'); +}); + +app.listen(port, () => { + console.log(`Beispiel-App, die auf Port ${port}`); +}); +``` + +Diese App startet einen Server und lauscht auf Port 3000 für Verbindungen. The app responds with "Hello World!" for requests +to the root URL (`/`) or *route*. Für jeden anderen Pfad wird es mit einem **404 Nicht gefunden** antworten. + +## Lokal laufen + +Erstelle zuerst ein Verzeichnis namens `myapp`, ändere es und führe `npm init` aus. Installieren Sie dann `Expres` als Abhängigkeit, wie in der [Installationsanleitung](/en/starter/installing). + +Erstelle im `myapp` Verzeichnis eine Datei namens `app.js` und kopiere den Code aus dem obigen Beispiel. + + + +Die `req` (Anfrage) und `res` (Antwort) sind genau die gleichen Objekte, die der Knoten anbietet, also kann +`req aufrufen. ipe()`, `req.on('data', callback)` und alles, was Sie sonst ohne Express +tun würden. + + + +Führen Sie die App mit dem folgenden Befehl aus: + +```bash +$ node app.js +``` + +Lade dann `http://localhost:3000/` in einem Browser, um die Ausgabe zu sehen. diff --git a/src/content/docs/de/5x/starter/installing.mdx b/src/content/docs/de/5x/starter/installing.mdx new file mode 100644 index 0000000000..5c8cda4b06 --- /dev/null +++ b/src/content/docs/de/5x/starter/installing.mdx @@ -0,0 +1,41 @@ +--- +title: Installiere +description: Erfahren Sie, wie Sie Express.js in Ihrer Node.js-Umgebung installieren, einschließlich der Einrichtung Ihres Projektverzeichnisses und der Verwaltung von Abhängigkeiten mit npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Bevor Sie beginnen, stellen Sie sicher, dass Sie [Node.js](https://nodejs.org/) 18 oder höher installiert haben. Erstellen Sie dann ein Verzeichnis für Ihre Anwendung und navigieren Sie hinein. + +```bash +mkdir myapp +cd myapp +``` + +Benutze den Befehl `npm init` um eine `package.json` Datei für deine Anwendung zu erstellen. +Für weitere Informationen darüber, wie `package.json` funktioniert, siehe [Spezifikationen für npm's package.json handling](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +Dieser Befehl fragt Sie nach einer Reihe von Dingen wie dem Namen und der Version Ihrer Anwendung. +Im Moment können Sie einfach RETURN drücken, um die Standardwerte für die meisten von ihnen zu akzeptieren, mit der folgenden Ausnahme: + +``` +eintragspunkt: (index.js) +``` + +Geben Sie `app.js` ein, oder was auch immer der Name der Hauptdatei sein soll. Wenn Sie `index.js` wollen, drücken Sie RETURN um den empfohlenen Dateinamen zu akzeptieren. + +Installieren Sie jetzt Express im `myapp` Verzeichnis und speichern Sie es in der Abhängigkeitsliste. Zum Beispiel: + +```bash +npm Express installieren +``` + +Um Express vorübergehend zu installieren und nicht zur Abhängigkeitsliste hinzufügen: + +```bash +npm express installieren --no-save +``` diff --git a/src/content/docs/de/5x/starter/static-files.mdx b/src/content/docs/de/5x/starter/static-files.mdx new file mode 100644 index 0000000000..f1c8dc894a --- /dev/null +++ b/src/content/docs/de/5x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Serviere statische Dateien in Express +description: Verstehen Sie, wie Sie statische Dateien wie Bilder, CSS und JavaScript in Express.js Anwendungen mit der integrierten 'static' Middleware bedienen können. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Um statische Dateien wie Bilder, CSS-Dateien und JavaScript-Dateien bereitzustellen, verwenden Sie die in Express integrierte Middleware-Funktion `express.static`. + +Die Funktionssignatur ist: + +```js +express.static(root, [options]); +``` + +Das `root` Argument gibt das Wurzelverzeichnis an, von dem aus statische Assets ausgeliefert werden sollen. +Für weitere Informationen zum Argument `options` siehe [express.static](/en/5x/api#express.static). + +Verwenden Sie zum Beispiel den folgenden Code, um Bilder, CSS-Dateien und JavaScript-Dateien in einem Verzeichnis mit dem Namen `public` auszugeben: + +```js +app.use(express.static('public')); +``` + +Jetzt kannst du die Dateien im `public` Verzeichnis laden: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express sucht die Dateien relativ zum statischen Verzeichnis, so dass der Name des statischen Verzeichnisses +nicht Teil der URL ist. + + + +Um mehrere statische Asset-Verzeichnisse zu verwenden, rufen Sie die `express.static` Middleware-Funktion mehrmals auf: + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express sucht die Dateien in der Reihenfolge, in der du die statischen Verzeichnisse mit der Middleware-Funktion `express.static` gesetzt hast. + + + +Für beste Ergebnisse Benutze einen Reverse +Proxy Cache um die Leistung von +zu verbessern und statische Assets zu bedienen. + + + +Um einen virtuellen Pfad-Präfix zu erstellen (wo der Pfad existiert eigentlich nicht im Dateisystem) für Dateien, die durch die `express. tatic` Funktion, [einen Mount-Pfad angeben](/en/5x/api#app.use) für das statische Verzeichnis angeben, wie unten angezeigt: + +```js +app.use('/static', express.static('public')); +``` + +Nun kannst du die Dateien, die sich im `public` Verzeichnis befinden, aus dem `/static` Pfadpräfix laden. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +Der Pfad, den du der `express.static` Funktion zur Verfügung stellst, ist jedoch relativ zu dem Verzeichnis, von dem aus du deinen `node` Prozess startest. Wenn Sie die Express-App aus einem anderen Verzeichnis ausführen, ist es sicherer, den absoluten Pfad des Verzeichnisses zu verwenden, das Sie verwenden möchten: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public')); +``` + +Weitere Informationen über die `serve-static` Funktion und ihre Optionen finden Sie unter [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/es/4x/advanced/developing-template-engines.md b/src/content/docs/es/4x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..39a63bd5b5 --- /dev/null +++ b/src/content/docs/es/4x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Desarrollar motores de plantillas para Express +description: Aprenda cómo desarrollar motores de plantillas personalizados para Express.js usando app.engine(), con ejemplos de creación e integración de su propia lógica de renderizado de plantillas. +--- + +Usa el método `app.engine(ext, callback)` para crear tu propio motor de plantillas. `ext` se refiere a la extensión del archivo, y `callback` es la función del motor de plantilla, que acepta los siguientes elementos como parámetros: la ubicación del archivo, el objeto de opciones y la función de devolución de llamada. + +El siguiente código es un ejemplo de implementación de un motor de plantillas muy simple para renderizar archivos `.ntl`. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +Tu aplicación ahora será capaz de procesar archivos `.ntl`. Crea un archivo llamado `index.ntl` en el directorio `views` con el siguiente contenido. + +```pug +#title# +#message# +``` + +Luego, crea la siguiente ruta en tu aplicación. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +Cuando hagas una solicitud a la página de inicio, `index.ntl` será renderizado como HTML. diff --git a/src/content/docs/es/4x/guide/behind-proxies.mdx b/src/content/docs/es/4x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..ec6a8e1c11 --- /dev/null +++ b/src/content/docs/es/4x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Expresar detrás de proxies +description: Aprenda cómo configurar las aplicaciones Express.js para que funcionen correctamente detrás de los proxies inversos, incluyendo el uso de la configuración del proxy de confianza para manejar las direcciones IP del cliente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Cuando se ejecuta una aplicación Express detrás de un proxy inverso, algunas de las APIs Express pueden devolver valores diferentes de los esperados. Para ajustarse a esto, la configuración de la aplicación `trust proxy` puede utilizarse para exponer la información proporcionada por el proxy inverso en las APIs Express. El problema más común son las APIs expresas que exponen la dirección IP del cliente pueden mostrar una dirección IP interna del proxy inverso. + + + +Al configurar la configuración del `proxy de confianza`, es importante entender la configuración exacta del proxy inverso +. Dado que esta configuración confiará en los valores proporcionados en la solicitud, es importante que +la combinación de la configuración en Express coincida con cómo funciona el proxy inverso. + + + +El ajuste de la aplicación `proxy de confianza` puede establecerse en uno de los valores listados en la siguiente tabla. + + + + + + + + + + + + + + + + + + + + + +
EscribaValor
Boolean +Si es `true`, la dirección IP del cliente se entiende como la entrada más a la izquierda en la cabecera `X-Forwarded-For`. + +Si es `false`, la aplicación se entiende como directamente frente al cliente y la dirección IP del cliente se deriva de `req.socket.remoteAddress`. Esta es la configuración por defecto. + + +Cuando se establece en `true`, es importante asegurarse de que el último proxy inverso en el que se confía es eliminar/sobrescribir todas las siguientes cabeceras HTTP: `X-Forwarded-For`, `X-Forwarded-Host`, y `X-Forwarded-Proto`, de lo contrario puede ser posible que el cliente proporcione cualquier valor. + +
direcciones IP +Una dirección IP, subred, o un array de direcciones IP y subredes en las que confiar como un proxy inverso. La siguiente lista muestra los nombres de subred preconfigurados: + +* bucle atrás - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +Puede establecer direcciones IP de cualquiera de las siguientes maneras: + +```js +app.set('trust proxy', 'loopback'); // especificar una única subred +app.set('trust proxy', 'loopback, 123.123.123.123'); // especificar una subred y una dirección +app. et('trust proxy', 'loopback, linklocal, uniquelocal'); // especifica múltiples subredes como CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // especifica múltiples subredes como un array +``` + +Cuando se especifica, las direcciones IP o las subredes están excluidas del proceso de determinación de direcciones, y la dirección IP no confiable más cercana al servidor de aplicaciones se determina como la dirección IP del cliente. Esto funciona comprobando si `req.socket.remoteAddress` es de confianza. Si es así, entonces cada dirección en `X-Forwarded-For` se marca de derecha a izquierda hasta la primera dirección no confiable. + +
Número +Utilice la dirección que es como máximo el número de saltos `n` de la aplicación Express. `req.socket.remoteAddress` es la primera salida, y el resto son buscados en la cabecera `X-Forwarded-For` de derecha a izquierda. Un valor de `0` significa que la primera dirección no confiable sería `req.socket.remoteAddress`, es decir, no hay proxy inverso. + + +Al usar esta configuración, es importante asegurarse de que no hay múltiplos, rutas de longitud diferente a la aplicación Express tal que el cliente puede ser menor que el número de saltos configurados de lo contrario es posible que el cliente proporcione cualquier valor. + +
Función +Implementación de confianza personalizada. + +```js +app.set('confiar en proxy', (ip) => { + if (ip === '127.0.0.1' || ip === '123.123.123. 23') + return true; // Iders confiables + else return false; +}); +``` + +
+ +Habilitar `proxy de confianza` tendrá el siguiente impacto: + +
    +
  • + El valor de [req.hostname](/en/api#req.hostname) se deriva del valor establecido en la cabecera + `X-Forwarded-Host`, que puede ser definido por el cliente o por el proxy. +
    • +
  • + `X-Forwarded-Proto` puede ser establecido por el proxy inverso para decirle a la aplicación si es `https` o + `http` o incluso un nombre inválido. Este valor se refleja en [req.protocol](/en/api#req.protocol). +
    • +
  • + Los valores [req.ip](/en/api#req.ip) y [req.ips](/en/api#req.ips) son poblados según la dirección del socket + y la cabecera `X-Forwarded-For`, comenzando en la primera dirección no confiable. +
    • +
+ +La configuración `trust proxy` se implementa usando el paquete [proxy-addr](https://www.npmjs.com/package/proxy-addr). Para obtener más información, consulte su documentación. diff --git a/src/content/docs/es/4x/guide/debugging.mdx b/src/content/docs/es/4x/guide/debugging.mdx new file mode 100644 index 0000000000..18a5f950b2 --- /dev/null +++ b/src/content/docs/es/4x/guide/debugging.mdx @@ -0,0 +1,123 @@ +--- +title: Depuración Express +description: Aprenda cómo habilitar y utilizar los registros de depuración en aplicaciones Express.js configurando la variable de entorno DEBUG para solucionar problemas mejorados. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Para ver todos los registros internos usados en Express, establece la variable de entorno `DEBUG` a +`express:*` al ejecutar tu aplicación. + +```bash +$ DEBUG=express:* nodo index.js +``` + +En Windows, utilice el comando correspondiente. + +```bash +> $env:DEBUG = "express:*"; nodo index.js +``` + +Ejecutando este comando en la aplicación predeterminada generada por el [generador expreso](/en/starter/generator) imprime la siguiente salida: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +Cuando se hace una solicitud a la aplicación, verá los registros especificados en el código Express: + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index.pug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +Para ver los registros sólo desde la implementación del router, establece el valor de `DEBUG` a `express:router`. De la misma manera, para ver los registros sólo desde la implementación de la aplicación, establece el valor de `DEBUG` a `express:application`, y así sucesivamente. + +## Aplicaciones generadas por `express` + +Una aplicación generada por el comando `express` utiliza el módulo `debug` y su espacio de nombres de depuración está cubierto por el nombre de la aplicación. + +Por ejemplo, si generaste la aplicación con \`$ muestra expresa, puedes habilitar las declaraciones de depuración con el siguiente comando: + +```bash +$ DEBUG=sample-app:* nodo ./bin/www +``` + +Puede especificar más de un espacio de nombres de depuración asignando una lista de nombres separados por comas: + +```bash +$ DEBUG=http,mail,express:* nodo index.js +``` + +## Opciones avanzadas + +Cuando se ejecuta a través de Node.js, puede establecer algunas variables de entorno que cambiarán el comportamiento del registro de depuración: + +| Nombre | Propósito | +| ------------------- | --------------------------------------------------------------------- | +| `DEBUG` | Habilita o deshabilita espacios de nombres específicos de depuración. | +| `DEBUG_COLORS` | Usar o no colores en la salida de depuración. | +| `DEBUG_DEPTH` | Profundidad de inspección de objetos. | +| `DEBUG_FD` | Descriptor de archivo en el que escribir salida de depuración. | +| `DEBUG_SHOW_HIDDEN` | Muestra propiedades ocultas en los objetos esperados. | + + + +Las variables de entorno que empiezan con `DEBUG_` acaban siendo convertidas en un objeto Options +que se usa con formateadores `%o`/`%O. Vea la documentación de Node.js para [`util.inspect()\`](https://nodejs.org/api/util#util_util_inspect_object_options) para la lista completa +. + + diff --git a/src/content/docs/es/4x/guide/error-handling.mdx b/src/content/docs/es/4x/guide/error-handling.mdx new file mode 100644 index 0000000000..c109279842 --- /dev/null +++ b/src/content/docs/es/4x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Manejo de errores +description: Descargue cómo Express.js maneja errores en código sincrónico y asíncrono, y aprenda a implementar middleware de manejo de errores personalizado para sus aplicaciones. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Error Handling* refers to how Express catches and processes errors that +occur both synchronously and asynchronously. Express viene con un manejador de error predeterminado +, así que no necesitas escribir el tuyo propio para empezar. + +## Errores de captura + +Es importante asegurarse de que Express capture todos los errores que ocurren mientras +ejecuta los manejadores de rutas y el middleware. + +Los errores que ocurren en el código sincrónico dentro de los manejadores de rutas y middleware +no requieren trabajo extra. Si el código sincrónico arroja un error, entonces Express hará +capturarlo y procesarlo. Por ejemplo: + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Express capturará esto por su cuenta. +}); +``` + +Para los errores devueltos por funciones asincrónicas invocadas por los manejadores de rutas +y middleware, debes pasarlos a la función `next()`, donde Express las capturará y procesará +. Por ejemplo: + +```js +app.get('/', (req, res, next) => { + fs. eadFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Pasar los errores a Express. + } else { + res. end(data); + } + }); +}); +``` + +A partir de Express 5, manejadores de rutas y middleware que devuelven una Promise +llamará automáticamente a `next(value)` cuando rechacen o lancen un error. +Por ejemplo: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = await getUserById(req.params.id); + res.send(user); +}); +``` + +Si `getUserById` arroja un error o rechaza, `next` será llamado con +el error arrojado o el valor rechazado. Si no se proporciona ningún valor rechazado, `next` +será llamado con un objeto de Error predeterminado proporcionado por el enrutador Express. + +If you pass anything to the `next()` function (except the string `'route'`), +Express regards the current request as being an error and will skip any +remaining non-error handling routing and middleware functions. + +Si la devolución de llamada en una secuencia no proporciona datos, sólo errores, puede simplificar +este código de la siguiente manera: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +En el ejemplo anterior, `next` es proporcionado como el callback para `fs.writeFile`, +que es llamado con o sin errores. Si no hay error, se ejecuta el segundo manejador +, de lo contrario Express catches y procesa el error. + +Debe capturar errores que ocurren en código asíncrono invocado por manejadores de ruta o un middleware +y pasarlos a Express para su procesamiento. Por ejemplo: + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + next(err); + } + }, 100); +}); +``` + +El ejemplo anterior utiliza un bloque `try...catch` para capturar errores en el código asincrónico +y pasarlos a Express. Si el bloque `try...catch` +fuera omitido, Express no capturaría el error ya que no es parte del código de manejador +sincrónico. + +Usa promesas para evitar la sobrecarga del bloque "intentar...atrapar" o al usar funciones +que devuelven promesas. Por ejemplo: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + . hen(() => { + throw new Error('BROKEN'); + }) + . atch(next); // Los errores se pasarán a Express. +}); +``` + +Since promises automatically catch both synchronous errors and rejected promises, +you can simply provide `next` as the final catch handler and Express will catch errors, +because the catch handler is given the error as the first argument. + +También podría utilizar una cadena de manejadores para depender de la captura de errores sincrónicos +, reduciendo el código asincrónico a algo trivial. Por ejemplo: + +```js +app.get('/', [ + function (req, res, next) { + fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals. ata = data; + siguiente(err); + }); + }, + function (req, res) { + res. ocals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +El ejemplo anterior tiene un par de declaraciones triviales de la llamada `readFile` +. Si `readFile` causa un error, entonces pasa el error a Express, de lo contrario +regresa rápidamente al mundo del manejo sincrónico de errores en el siguiente manejador +en la cadena. Luego, el ejemplo anterior intenta procesar los datos. Si esto falla, entonces el gestor de errores sincrónico +lo capturará. Si hubiera hecho este procesamiento dentro de +el callback `readFile`, entonces la aplicación podría salir y los manejadores de error Express +no se ejecutarían. + +Whichever method you use, if you want Express error handlers to be called in and the +application to survive, you must ensure that Express receives the error. + +## El gestor de errores por defecto + +Express viene con un gestor de errores integrado que se encarga de cualquier error que pueda encontrarse en la aplicación. Esta función middleware por defecto se añade al final de la pila de funciones de middleware. + +Si pasas un error a `next()` y no lo gestionas en un controlador +error personalizado, será manejado por el gestor de errores integrado; el error será +escrito al cliente con el stack trace. El stack trace no está incluido +en el entorno de producción. + + + +Establece la variable de entorno `NODE_ENV` a `production`, para ejecutar la aplicación en el modo de producción. + + + +When an error is written, the following information is added to the +response: + +* El `res.statusCode` se establece desde `err.status` (o `err.statusCode`). Si + este valor está fuera del rango 4xx o 5xx, se establecerá a 500. +* El `res.statusMessage` se establece de acuerdo al código de estado. +* El cuerpo será el HTML del mensaje del código de estado cuando en el entorno + de producción, de lo contrario será `err.stack`. +* Cualquier cabecera especificada en un objeto `err.headers`. + +Si llama a `next()` con un error después de haber comenzado a escribir la respuesta +(por ejemplo, si encuentras un error al transmitir la respuesta +al cliente), el gestor de errores Express por defecto cierra la conexión +y falla la solicitud. + +Así que cuando añada un manejador de errores personalizado, debe delegar a +el manejador de errores predeterminado Express cuando los encabezados +ya han sido enviados al cliente: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Tenga en cuenta que el manejador de errores por defecto puede activarse si llama a `next()` con un error +en su código más de una vez, incluso si el middleware está configurado para manejar errores personalizados. + +Otro middleware de manejo de error se puede encontrar en [Express middleware](/en/resources/middleware). + +## Manejadores de errores escritos + +Define las funciones de middleware de la misma manera que otras funciones de middleware, +excepto las funciones de manejo de errores tienen cuatro argumentos en lugar de tres: +`(err, req, res, next)`. Por ejemplo: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Usted define middleware manejado por errores últimamente, después de otras `app.use()` y llamadas de rutas; por ejemplo: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser. rlencoded({ + extendido: true, + }) +); +app.use(bodyParser.json()); +app. se(methodOverride()); +app.use((err, req, res, next) => { + // lógica +}); +``` + +Las respuestas desde dentro de una función middleware pueden estar en cualquier formato, como una página de error HTML, un mensaje simple, o una cadena JSON. + +For organizational (and higher-level framework) purposes, you can define +several error-handling middleware functions, much as you would with +regular middleware functions. Por ejemplo, para definir un manejador de errores +para las solicitudes realizadas usando `XHR` y las que no tienen: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app. se( + bodyParser.urlencoded({ + extendido: true, + }) +); +app. se(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +En este ejemplo, el genérico `logErrors` podría escribir una solicitud y +información de error a `stderr`, por ejemplo: + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +También en este ejemplo, `clientErrorHandler` se define de la siguiente manera; en este caso, el error se pasa explícitamente al siguiente. + +Tenga en cuenta que cuando *no* llama "siguiente" en una función de manejo de errores, usted es responsable de escribir (y terminar) la respuesta. De lo contrario, esas solicitudes se "colgarán" y no serán elegibles para la recolección de basura. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500). end({ error: 'Something failed!' }); + } else { + next(err); + } +} +``` + +Implementa la función "catch-all" `errorHandler` como sigue (por ejemplo): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +Si tiene un manejador de ruta con múltiples funciones de callback, puede utilizar el parámetro `route` para saltar al siguiente manejador de ruta. Por ejemplo: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user. asPaid) { + // continúa manejando esta solicitud + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent. ind((err, doc) => { + if (err) return next(err); + res. son(doc); + }); + } +); +``` + +En este ejemplo, el manejador `getPaidContent` se omitirá pero cualquier manejador restante en `app` para `/a_route_behind_paywall` continuaría siendo ejecutado. + + + +Las llamadas a `next()` y `next(err)` indican que el controlador actual está completo y en qué estado. +`next(err)` omitirá todos los manejadores restantes en la cadena, excepto aquellos que están configurados a +errores de manejo como se describe arriba. + + diff --git a/src/content/docs/es/4x/guide/overriding-express-api.md b/src/content/docs/es/4x/guide/overriding-express-api.md new file mode 100644 index 0000000000..9be44e70df --- /dev/null +++ b/src/content/docs/es/4x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Reemplazar la API Express +description: Descubra cómo personalizar y extender la API de Express.js reemplazando métodos y propiedades en los objetos de solicitud y respuesta usando prototipos. +--- + +La API Express consiste en varios métodos y propiedades sobre los objetos de solicitud y respuesta. Estos son heredados por prototipo. Hay dos puntos de extensión para la API Express: + +1. Los prototipos globales en `express.request` y `express.response`. +2. prototipos específicos de la aplicación en `app.request` y `app.response`. + +Alterar los prototipos globales afectará a todas las aplicaciones cargadas Express en el mismo proceso. Si se desea, las alteraciones pueden hacerse específicas de la aplicación sólo modificando los prototipos específicos de la aplicación después de crear una nueva aplicación. + +## Métodos + +Puede anular la firma y el comportamiento de los métodos existentes con los suyos, asignando una función personalizada. + +A continuación se muestra un ejemplo de anular el comportamiento de [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +La implementación anterior cambia completamente la firma original de `res.sendStatus`. Ahora acepta un código de estado, tipo de codificación, y el mensaje que se enviará al cliente. + +El método sobreescrito ahora puede utilizarse de esta manera: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## Propiedades + +Las propiedades en la API Express son tamaño: + +1. Propiedades asignadas (ej: `req.baseUrl`, `req.originalUrl`) +2. Definido como getters (ej: `req.secure`, `req.ip`) + +Dado que las propiedades de la categoría 1 se asignan dinámicamente a los objetos `request` y `response` en el contexto del ciclo actual de petición-respuesta, su comportamiento no puede ser anulado. + +Las propiedades de la categoría 2 se pueden sobrescribir usando la API Express de extensiones API. + +El siguiente código reescribe cómo se derivará el valor de `req.ip`. Ahora, simplemente devuelve el valor de la cabecera de petición `Client-IP`. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Prototipo + +Para proporcionar la API Express, los objetos de solicitud / respuesta pasados a Express (a través de `app(req, res)`, por ejemplo) necesita heredar de la misma cadena prototipo. Por defecto, esto es `http.IncomingRequest.prototype` para la solicitud y `http.ServerResponse.prototype` para la respuesta. + +A menos que sea necesario, se recomienda que esto se haga únicamente a nivel de aplicación, en lugar de a nivel global. Además, tenga cuidado de que el prototipo que se está utilizando coincida con la funcionalidad lo más cerca posible de los prototipos predeterminados. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/es/4x/guide/routing.mdx b/src/content/docs/es/4x/guide/routing.mdx new file mode 100644 index 0000000000..7735a472cf --- /dev/null +++ b/src/content/docs/es/4x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Ruta +description: Aprenda cómo definir y usar rutas en aplicaciones Express.js, incluyendo métodos de ruta, rutas de ruta, parámetros, y usando Router para rutas modulares. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* se refiere a cómo responden los extremos (URIs) de una aplicación a las peticiones del cliente. +Para una introducción al enrutamiento, consulte [Enrutamiento básico](/en/starter/basic-routing). + +Define enrutamiento usando métodos del objeto Express `app` que corresponden a métodos HTTP; +por ejemplo, `app. et()` para manejar solicitudes GET y `app.post` para manejar solicitudes POST. Para una lista completa, +vea [app.METHOD](/en/5x/api#app.METHOD). También puedes usar [app.all()](/en/5x/api#app.all) para manejar todos los métodos HTTP y [app. se()](/en/5x/api#app.use) a +especificar middleware como función de callback (Ver [Usando middleware](/en/guide/using-middleware) para más detalles). + +Estos métodos de enrutamiento especifican una función de callback (a veces llamada "funciones manejadoras") llamada cuando la aplicación recibe una petición a la ruta especificada (endpoint) y el método HTTP. En otras palabras, la aplicación "escucha" para peticiones que coinciden con el/los método(s) especificado(s), y cuando detecta una coincidencia, llama a la función de callback especificada. + +De hecho, los métodos de enrutamiento pueden tener más de una función de callback como argumentos. +Con múltiples funciones de callback, es importante proporcionar `next` como un argumento a la función de callback y luego llamar `next()` dentro del cuerpo de la función para desactivar el control +al siguiente callback. + +El siguiente código es un ejemplo de una ruta muy básica. + +```js +const express = require('express'); +const app = express(); + +// responden con "Hola mundo" cuando se hace una solicitud GET a la página de inicio +aplicación. et('/', (req, res) => { + res.send('hola mundo'); +}); +``` + +## Métodos de ruta + +Un método de ruta se deriva de uno de los métodos HTTP y se adjunta a una instancia de la clase `express`. + +El siguiente código es un ejemplo de rutas definidas para los métodos `GET` y `POST` a la raíz de la aplicación. + +```js +// Ruta del método GET +app.get('/', (req, res) => { + res. end('GET request to the homepage'); +}); + +// método POST route +app. ost('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Express soporta métodos que corresponden a todos los métodos de petición HTTP: `get`, `post`, y así sucesivamente. +Para una lista completa, vea [app.METHOD](/en/5x/api#app.METHOD). + +Hay un método especial de enrutamiento, `app.all()`, usado para cargar funciones de middleware en una ruta para *all* métodos de petición HTTP. Por ejemplo, el siguiente manejador se ejecuta para peticiones a la ruta `"/secret"` ya sea usando `GET`, `POST`, `PUT`, `DELETE`, o cualquier otro método de solicitud HTTP soportado en el [módulo http](https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Acceder a la sección secreta ...'); + next(); // pasar el control al siguiente manejador +}); +``` + +## Rutas de ruta + +Las rutas de ruta, en combinación con un método de solicitud, definen los extremos en los que se pueden realizar las solicitudes. Las rutas pueden ser cadenas, patrones de cadenas o expresiones regulares. + + + +En expreso 5, los caracteres `? , `+`, `\*`, `[]`, y `()\` son manejados de manera diferente que en la versión +4, por favor revisa la [guía de migración](/en/guide/migrating-5#path-syntax) para más información. + + + + + +En expreso 4, los caracteres de expresión regular como `$` necesitan ser escapados con un `\`. + + + + + +Express usa [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) para emparejar las rutas de la ruta +; vea la documentación de la ruta a regexp para todas las posibilidades de definir rutas de la ruta. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) is a handy tool for +testing basic Express routes, although it does not support pattern matching. + + + +Las cadenas de consulta no son parte de la ruta de la ruta. + +### Rutas de ruta basadas en cadenas + +Esta ruta coincidirá con las peticiones a la ruta raíz, `/`. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +Esta ruta coincidirá con las peticiones a `/about`. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +Esta ruta de ruta coincidirá con peticiones a `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Rutas de ruta basadas en patrones de cadenas + + + +Los patrones de cadenas en Express 5 ya no funcionan. Consulte la guía de migración + para obtener más información. + + + +Esta ruta de ruta coincidirá con `acd` y `abcd`. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +Esta ruta coincidirá con `abcd`, `abbcd`, `abbbcd`, y así sucesivamente. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +Esta ruta de ruta coincidirá con `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd`, y así sucesivamente. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +Esta ruta coincidirá con `/abe` y `/abcde`. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Rutas de ruta basadas en expresiones regulares + +Esta ruta coincidirá con cualquier cosa con una "a". + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +Esta ruta coincidirá con `butterfly` y `dragonfly`, pero no `butterflyman`, `dragonflyman`, y así sucesivamente. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Parámetros de ruta + +Los parámetros de ruta se llaman segmentos de URL que se utilizan para capturar los valores especificados en su posición en la URL. Los valores capturados son poblados en el objeto `req.params`, con el nombre del parámetro de ruta especificado en la ruta como sus claves respectivas. + +``` +Ruta de ruta: /users/:userId/books/:bookId +URL de petición: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +Para definir rutas con parámetros de ruta, simplemente especifique los parámetros de ruta en la ruta como se muestra a continuación. + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +El nombre de los parámetros de la ruta debe estar compuesto de "caracteres de palabra" ([A-Za-z0-9_]). + + + +Dado que los guiones (`-`) y el punto (`.`) se interpretan literalmente, pueden ser utilizados junto con parámetros de ruta para propósitos útiles. + +``` +Ruta de ruta: /flights/:from-:to +Request URL: http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Ruta de ruta: /plantae/:genus.:species +Request URL: http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +En expreso 5, no se admiten caracteres de expresión regular en rutas para más información, por favor +consulte la [guía de migración](/en/guide/migrating-5#path-syntax). + + + +Para tener más control sobre la cadena exacta que puede coincidir con un parámetro de ruta, puede añadir una expresión regular entre paréntesis (`()`): + +``` +Ruta de ruta: /user/:userId(\d+) +URL de Solicitud: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Debido a que la expresión regular es generalmente parte de una cadena literal, Asegúrate de escapar cualquier `\` +caracteres con una barra inversa adicional, por ejemplo `\d+`. + + + + +En Express 4.x, el carácter `*` en expresiones regulares no se interpreta de la forma habitual. Como un workaround, usa `{0,}` en lugar de `*`. Es probable que esto se arregle en Express 5. + + +## Manejadores de rutas + +Puedes proporcionar múltiples funciones de callback que se comportan como [middleware](/en/guide/using-middleware) para gestionar una solicitud. La única excepción es que estos callbacks podrían invocar a `next('route')` para evitar las llamadas restantes de ruta. Se puede utilizar este mecanismo para imponer condiciones previas a una ruta, luego pasar el control a las rutas posteriores si no hay razón para proceder con la ruta actual. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params. d === '0') { + return next('route'); + } + res. end(`Usuario ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Controlador especial para el usuario ID 0'); +}); +``` + +En este ejemplo: + +* `GET /user/5` → manejado por primera ruta → envía "Usuario 5" +* `GET /user/0` → primera ruta llama a `next('ruta')`, saltando a la siguiente ruta `/user/:id` + +Los manejadores de rutas pueden ser en forma de una función, un array de funciones o combinaciones de ambos, como se muestra en los siguientes ejemplos. + +Una única función de callback puede manejar una ruta. Por ejemplo: + +```js +app.get('/example/a', (req, res) => { + res.send('Hola de A!'); +}); +``` + +Más de una función de callback puede manejar una ruta (asegúrese de especificar el objeto `siguiente`). Por ejemplo: + +```js +app.get( + '/example/b', + (req, res, next) => { + consola. og('la respuesta será enviada por la siguiente función . .'); + siguiente(); + }, + (req, res) => { + res. end('Hola de B!'); + } +); +``` + +Una matriz de funciones de callback puede manejar una ruta. Por ejemplo: + +```js +const cb0 = function (req, res, next) { + consola. og('CB0'); + siguiente(); +}; + +const cb1 = function (req, res, next) { + consola. og('CB1'); + siguiente(); +}; + +const cb2 = function (req, res) { + res. end('Hola de C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +Una combinación de funciones independientes y arreglos de funciones puede manejar una ruta. Por ejemplo: + +```js +const cb0 = function (req, res, next) { + consola. og('CB0'); + siguiente(); +}; + +const cb1 = function (req, res, next) { + consola. og('CB1'); + siguiente(); +}; + +app. et( + '/example/d', + [cb0, cb1], + (req, res, next) => { + consola. og('la respuesta será enviada por la siguiente función . .'); + siguiente(); + }, + (req, res) => { + res. end('Hola de D!'); + } +); +``` + +## Métodos de respuesta + +Los métodos en el objeto de respuesta (`res`) en la siguiente tabla pueden enviar una respuesta al cliente y terminar el ciclo de solicitud y respuesta. Si ninguno de estos métodos es llamado desde un gestor de rutas, la petición del cliente se dejará colgada. + +| Método | Descripción | +| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | Solicitar un archivo para ser descargado. | +| [res.end()](/en/5x/api#res.end) | Terminar el proceso de respuesta. | +| [res.json()](/en/5x/api#res.json) | Enviar una respuesta JSON. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Envía una respuesta JSON con soporte JSONP. | +| [res.redirect()](/en/5x/api#res.redirect) | Redirigir una solicitud. | +| [res.render()](/en/5x/api#res.render) | Procesar una plantilla de vista. | +| [res.send()](/en/5x/api#res.send) | Enviar una respuesta de varios tipos. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Enviar un archivo como un flujo de octet. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Establece el código de estado de respuesta y envía su representación de cadena como el cuerpo de respuesta. | + +## app.route() + +Puede crear manejadores de rutas encadenables para una ruta usando `app.route()`. +Debido a que la ruta se especifica en una única ubicación, la creación de rutas modulares es útil, al igual que la reducción de redundancia y tipografías. Para más información sobre rutas, vea: [documentación Router() ](/en/5x/api#router). + +Aquí hay un ejemplo de manejadores encadenados de rutas que se definen usando `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res. end('Obtén un libro al azar'); + }) + . ost((req, res) => { + res.send('Agregar un libro'); + }) + . ut((req, res) => { + res.send('Actualizar el libro'); +}); +``` + +## express.Router + +Utilice la clase `express.Router` para crear manejadores modulares de rutas. Una instancia de `Router` es un sistema completo de middleware y enrutamiento; por esta razón, a menudo se le denomina "mini-app". + +El siguiente ejemplo crea un router como módulo, carga una función de middleware en él, define algunas rutas y monta el módulo del router en una ruta de la aplicación principal. + +Crea un archivo de enrutador llamado `birds.js` en el directorio de la aplicación, con el siguiente contenido: + +```js +const express = require('express'); +const router = express. outer(); + +// middleware que es específico para este router +const timeLog = (req, res, next) => { + consola. og('Hora: ', Date.now()); + siguiente(); +}; enrutador +. se(timeLog); + +// define la ruta de la página de inicio +router.get('/', (req, res) => { + res. end('Página de inicio de aves'); +}); +// define la ruta +router. et('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Luego, cargue el módulo de enrutador en la aplicación: + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +La aplicación ahora será capaz de manejar solicitudes a `/birds` y `/birds/about`, así como llamar a la función de middleware `timeLog` que es específica de la ruta. + +Pero si la ruta padre `/birds` tiene parámetros de ruta, no será accesible por defecto desde las subrutas. Para hacerlo accesible, necesitarás pasar la opción `mergeParams` al constructor de Router [reference](/en/5x/api#app.use). + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/es/4x/guide/using-middleware.mdx b/src/content/docs/es/4x/guide/using-middleware.mdx new file mode 100644 index 0000000000..07d3417df7 --- /dev/null +++ b/src/content/docs/es/4x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Usando middleware +description: Aprenda cómo usar middleware en aplicaciones Express.js, incluyendo middleware de nivel de aplicación y router, manejo de errores, e integración de middleware de terceros. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express es un framework web de enrutamiento y middleware que tiene una funcionalidad mínima propia: Una aplicación Express es esencialmente una serie de llamadas a funciones de middleware. + +Las funciones *Middleware* son funciones que tienen acceso al [objeto de solicitud](/en/5x/api#req) (`req`), el [objeto de respuesta](/en/5x/api#res) (`res`), y la siguiente función de middleware en el ciclo de solicitud y respuesta de la aplicación. La siguiente función middleware se denota comúnmente por una variable llamada `next`. + +Las funciones de Middleware pueden realizar las siguientes tareas: + +* Ejecutar cualquier código. +* Realizar cambios en la solicitud y en los objetos de respuesta. +* Terminar el ciclo de solicitud de respuesta. +* Llame a la siguiente función de middleware en la pila. + +Si la función actual de middleware no termina el ciclo de solicitud de respuesta, debe llamar a `next()` para pasar el control a la siguiente función de middleware. De lo contrario, la solicitud quedará colgada. + +Una aplicación Express puede utilizar los siguientes tipos de middleware: + +* [Middleware de nivel de aplicación](#middleware.application) +* [Middleware de nivel superior](#middleware.router) +* [Middleware de manejo de errores](#middleware.error-handling) +* [Middleware incorporado](#middleware.built-in) +* [Middleware de terceros](#middleware.third-party) + +Puede cargar middleware de nivel de aplicación y de enrutador con una ruta de montaje opcional. +También puede cargar una serie de funciones de middleware juntas, lo que crea un substack del sistema de middleware en un punto de montaje. + +## Middleware de nivel de aplicación + +Vincular middleware a una instancia del [objeto de aplicación](/en/5x/api#app) usando `app.use()` y `app. ETHOD()` funciona, donde `METHOD` es el método HTTP de la petición que la función middleware maneja (como GET, PUT o POST) en minúsculas. + +Este ejemplo muestra una función de middleware sin ruta de montaje. La función se ejecuta cada vez que la aplicación recibe una solicitud. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +Este ejemplo muestra una función middleware montada en la ruta `/user/:id`. La función se ejecuta para cualquier tipo de petición +HTTP en la ruta `/user/:id`. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +Este ejemplo muestra una ruta y su función manejadora (middleware system). La función maneja peticiones GET a la ruta `/user/:id`. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USUARIO'); +}); +``` + +He aquí un ejemplo de carga de una serie de funciones de middleware en un punto de montaje, con una ruta de montaje. +Ilustra un substack de middleware que imprime la información de la petición para cualquier tipo de petición HTTP a la ruta `/user/:id`. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + consola. og('Tipo de solicitud:', req.method); + siguiente(); + } +); +``` + +Los manejadores de rutas le permiten definir múltiples rutas para una ruta. El siguiente ejemplo define dos rutas para peticiones GET a la ruta `/user/:id`. La segunda ruta no causará ningún problema, pero nunca se llamará porque la primera ruta termina el ciclo de solicitud de respuesta. + +Este ejemplo muestra un substack de middleware que maneja peticiones GET a la ruta `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req. arams.id); + siguiente(); + }, + (req, res, next) => { + res. end('Información de usuario'); + } +); + +// manejador para la ruta /user/:id, que imprime el ID de usuario +app. et('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +Para omitir el resto de las funciones de middleware desde una pila de middleware de router, llame a `next('ruta')` para pasar el control a la siguiente ruta. + + + +`next('ruta')` solo funcionará en funciones de middleware que fueron cargadas usando las funciones +`app.METHOD()` o `router.METHOD()`. + + + +Este ejemplo muestra un substack de middleware que maneja peticiones GET a la ruta `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + // si el ID de usuario es 0, saltar a la siguiente ruta + si (req. aramas. d === '0') siguiente('ruta'); + // de lo contrario pasa el control a la siguiente función de middleware en esta pila + si no siguiente(); + }, + (req, res, next) => { + // envía una respuesta regular + res. end('regular'); + } +); + +// manejador para la ruta /user/:id, que envía una respuesta especial +app. et('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +Middleware también puede ser declarado en una matriz para reusabilidad. + +Este ejemplo muestra una matriz con un substack de middleware que maneja peticiones GET en la ruta `/user/:id` + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req. riginalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Request Type:', req. ethod); + siguiente(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app. et('/user/:id', logStuff, (req, res, next) => { + res.send('Información de usuario'); +}); +``` + +## Middleware de nivel remoto + +El middleware Router-level funciona de la misma manera que el middleware a nivel de aplicación, excepto que está vinculado a una instancia de `express.Router()`. + +```js +const router = express.Router(); +``` + +Carga el middleware a nivel de enrutador usando las funciones `router.use()` y `router.METHOD()`. + +El siguiente código de ejemplo replica el sistema middleware que se muestra arriba para el middleware de nivel de aplicación, mediante el uso de router-level middleware: + +```js +const express = require('express'); +const app = express(); +const router = express. outer(); + +// una función de middleware sin ruta de montaje. Este código se ejecuta para cada petición al router +. se((req, res, next) => { + console.log('Hora:', Date. ow()); + siguiente(); +}); + +// un substack de middleware muestra información de petición para cualquier tipo de petición HTTP al router /user/:id path +. se( + '/user/:id', + (req, res, next) => { + console.log('URL de solicitud:', req. riginalUrl); + next(); + }, + (req, res, next) => { + consola. og('Tipo de solicitud:', req. ethod); + next(); + } +); + +// un substack de middleware que maneja las solicitudes GET al router /user/:id path +. et( + '/user/:id', + (req, res, next) => { + // si el ID de usuario es 0, saltar al siguiente router + if (req. aramas. d === '0') siguiente('ruta'); + // de lo contrario pasar el control a la siguiente función de middleware en esta pila + más siguiente(); + }, + (req, res, next) => { + // renderiza una página regular + res. ender('regular'); + } +); + +// manejador para la ruta /user/:id, que renderiza una página especial +router. et('/user/:id', (req, res, next) => { + consola. og(req.params.id); + res.render('special'); +}); + +// monta el router en la aplicación +app.use('/', router); +``` + +Para omitir el resto de las funciones de middleware del enrutador, llama a `next('router')` +para pasar el control de vuelta fuera de la instancia del enrutador. + +Este ejemplo muestra un substack de middleware que maneja peticiones GET a la ruta `/user/:id`. + +```js +const express = require('express'); +const app = express(); +const router = express. outer(); + +// predice el enrutador con un cheque y rescinda cuando sea necesario enrutador +. se((req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router. et('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// usa el enrutador y 401 cualquier cosa que caiga a través de +aplicación. se('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## Middleware de manejo de errores + + + +Middleware manejado por errores siempre toma *four* argumentos. Debe proporcionar cuatro argumentos para +identificarlo como una función de middleware que maneja errores. Incluso si no necesitas usar el objeto `next` +, debes especificarlo para mantener la firma. De lo contrario, el objeto `siguiente` será +interpretado como middleware regular y fallará al manejar errores. + + + +Define las funciones de middleware de la misma manera que otras funciones de middleware, excepto con cuatro argumentos en lugar de tres, específicamente con la firma `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Para más detalles sobre el middleware de manejo de errores, vea: [Gestión de errores](/en/guide/error-handling). + +## Middleware incorporado + +A partir de la versión 4.x, Express ya no depende de [Connect](https://github.com/senchalabs/connect). Las funciones +del middleware que anteriormente estaban incluidas con Express están ahora en módulos separados; vea [la lista de funciones de middleware](https://github.com/senchalabs/connect#middleware). + +Express tiene las siguientes funciones de middleware incorporadas: + +* [express.static](/en/5x/api#express.static) sirve activos estáticos como archivos HTML, imágenes, etc. +* [express.json](/en/5x/api#express.json) analiza las solicitudes entrantes con cargas útiles JSON. **NOTA: Disponible con Express 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) analiza las solicitudes entrantes con payloads codificados por URL. **NOTA: Disponible con Express 4.16.0+** + +## Middleware de terceros + +Utilice middleware de terceros para añadir funcionalidad a aplicaciones Express. + +Instale el módulo Node.js para la funcionalidad requerida, luego guárdelo en su aplicación a nivel de aplicación o a nivel de enrutador. + +El siguiente ejemplo ilustra la instalación y carga de la función middleware `cookie-parser`. + +```bash +$ npm instalar cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// cargar el middleware de análisis de cookies +app.use(cookieParser()); +``` + +Para una lista parcial de funciones de middleware de terceros que se utilizan comúnmente con Express, vea: [Middleware de terceros](../resources/middleware). diff --git a/src/content/docs/es/4x/guide/using-template-engines.mdx b/src/content/docs/es/4x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..0de07ab115 --- /dev/null +++ b/src/content/docs/es/4x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Utilizando motores de plantillas con Express +description: Descubra cómo integrar y utilizar motores de plantillas como Pug, Handlebars y EJS con Express.js para renderizar páginas HTML dinámicas eficientemente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Un *template engine* le permite usar plantillas estáticas en su aplicación. En tiempo de ejecución, el motor de plantillas reemplaza variables +en un archivo de plantilla con valores reales. y transforma la plantilla en un archivo HTML enviado al cliente. +Este enfoque facilita el diseño de una página HTML. + +El [generador de aplicaciones Express](/en/starter/generator) utiliza [Pug](https://pugjs.org/api/getting-started.html) como predeterminado, pero también soporta [Handlebars](https://www.npmjs.com/package/handlebars), y [EJS](https://www.npmjs.com/package/ejs), entre otros. + +Para renderizar archivos de plantilla, establezca las siguientes [propiedades de configuración de aplicación](/en/4x/api#app.set), en el `app.js` por defecto creado por el generador: + +* `vistas`, el directorio donde están ubicados los archivos de plantilla. Ej: `app.set('vistas', './views')`. + Esto por defecto es el directorio `views` en el directorio raíz de la aplicación. +* `ver engine`, el motor de plantillas a usar. Por ejemplo, para usar el motor de plantillas Pug: `app.set('view engine', 'pug')`. + +A continuación, instale el correspondiente paquete npm del motor de plantillas; por ejemplo para instalar Pug: + +```bash +$ npm install pug --save +``` + + +Motores de plantillas compatibles con Expresiones, tales como Pug exportar una función llamada `__express(filePath, options, callback)`, +que `res.render()` llama para renderizar el código de plantilla. + +Algunos motores de plantillas no siguen esta convención. La biblioteca [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +sigue esta convención mapeando todos los motores de plantillas populares de Node.js, y por lo tanto funciona perfectamente dentro de Express. + + + +Después de que el motor de vista esté definido, no tiene que especificar el motor o cargar el módulo de motor de plantillas en su aplicación; +Express carga el módulo internamente, por ejemplo: + +```js +app.set('ver motor', 'pug'); +``` + +Luego, crea un archivo de plantilla Pug llamado `index.pug` en el directorio `views`, con el siguiente contenido: + +```pug +html + head + title= title + body + h1= message +``` + +Crea una ruta para representar el archivo `index.pug`. Si la propiedad `view engine` no está definida, +debe especificar la extensión del archivo `view`. De lo contrario, puede omitirlo. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: '¡Hola!' }); +}); +``` + +Cuando hagas una solicitud a la página de inicio, el archivo `index.pug` será renderizado como HTML. + +La caché del motor de vistas no almacena en caché el contenido de la salida de la plantilla, sólo la misma plantilla subyacente. La vista todavía se vuelve a procesar con cada petición incluso cuando la caché está encendida. diff --git a/src/content/docs/es/4x/guide/writing-middleware.mdx b/src/content/docs/es/4x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..6acd234dca --- /dev/null +++ b/src/content/docs/es/4x/guide/writing-middleware.mdx @@ -0,0 +1,239 @@ +--- +title: Escribiendo middleware para uso en aplicaciones Express +description: Aprenda cómo escribir funciones personalizadas de middleware para aplicaciones Express.js, incluyendo ejemplos y mejores prácticas para mejorar la gestión de peticiones y respuestas. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Las funciones *Middleware* son funciones que tienen acceso al [objeto de solicitud](/en/5x/api#req) (`req`), el [objeto de respuesta](/en/5x/api#res) (`res`), y la función `next` en el ciclo de solicitud y respuesta de la aplicación. La función `siguiente` es una función en el router Express que, cuando se invoca, ejecuta el middleware sucediendo al middleware actual. + +Las funciones de Middleware pueden realizar las siguientes tareas: + +* Ejecutar cualquier código. +* Realizar cambios en la solicitud y en los objetos de respuesta. +* Terminar el ciclo de solicitud de respuesta. +* Llama al siguiente middleware en la pila. + +Si la función actual de middleware no termina el ciclo de solicitud de respuesta, debe llamar a `next()` para pasar el control a la siguiente función de middleware. De lo contrario, la solicitud quedará colgada. + +La siguiente figura muestra los elementos de una llamada a una función de middleware: + +
+ + + + + +
+Elementos de una llamada a función middleware + +
método HTTP para el cual se aplica la función middleware.
+ +
+ Ruta (ruta) para la que se aplica la función middleware. +
+ +
+ La función Middleware. +
+ +
+ Argumento de llamada a la función middleware, llamado "siguiente" por convención. +
+ +
+ HTTP argumento de respuesta a la función de middleware, llamada "res" por convención + . +
+ +
HTTP solicita un argumento a la función de middleware, llamado "req" por convención.
+
+
+ +A partir de Express 5, las funciones de middleware que devuelven una Promise llamarán `next(value)` cuando rechacen o lancen un error. `next` será llamado con el valor rechazado o con el error arrojado. + +## Ejemplo + +He aquí un ejemplo de una simple aplicación "Hola Mundo" Express. +El resto de este artículo definirá y añadirá tres funciones de middleware a la aplicación: +una llamada `myLogger` que imprime un simple mensaje de registro, uno llamado `requestTime` que +muestra la marca de tiempo de la petición HTTP, y uno llamado `validateCookies` que valida las cookies entrantes. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('¡Hola Mundo!'); +}); + +app.listen(3000); +``` + +### Función Middleware myLogger + +Aquí hay un ejemplo simple de una función middleware llamada "myLogger". Esta función solo imprime +"LOGGED" cuando una solicitud a la aplicación pasa a través de ella. La función middleware está asignada a una variable +llamada `myLogger`. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +Tenga en cuenta la llamada anterior a `next()`. Llamar a esta función invoca la siguiente función de middleware en +la aplicación. La función `next()` no es parte del Nodo. s o Express API, pero es el tercer argumento +que se pasa a la función middleware. La función `next()` podría ser nombrada cualquier cosa, +pero por convención siempre se llama "siguiente". Para evitar la confusión, utilice siempre esta convención. + + + +Para cargar la función middleware, llama a `app.use()`, especificando la función middleware. +Por ejemplo, el siguiente código carga la función middleware `myLogger` antes de la ruta a la ruta raíz (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + consola. og('LOGGED'); + siguiente(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('¡Hola Mundo!'); +}); + +app.listen(3000); +``` + +Cada vez que la aplicación recibe una solicitud, imprime el mensaje "LOGGED" en el terminal. + +El orden de carga de middleware es importante: las funciones de middleware que se cargan primero también se ejecutan primero. + +Si `myLogger` es cargado después de la ruta a la ruta raíz, la solicitud nunca llega a ella y la aplicación no imprime "LOGGED", porque el manejador de rutas de la ruta raíz termina el ciclo de solicitud de respuesta. + +La función Middleware `myLogger` simplemente imprime un mensaje, luego pasa la solicitud a la siguiente función de middleware en la pila llamando a la función `next()`. + +### Tiempo de solicitud de la función Middleware + +A continuación, crearemos una función de middleware llamada "requestTime" y agregaremos una propiedad llamada `requestTime` +al objeto de la solicitud. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +La aplicación ahora utiliza la función de middleware `requestTime`. Además, la función de callback de la ruta raíz utiliza la propiedad que la función middleware añade a `req` (el objeto de la solicitud). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req. equestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app. et('/', (req, res) => { + let responseText = '¡Hola Mundo!
'; + responseText += `Solicitado en: ${req.requestTime}`; + res. end(responseText); +}); + +app.listen(3000); +``` + +Cuando hace una solicitud a la raíz de la aplicación, la aplicación ahora muestra la marca de tiempo de su solicitud en el navegador. + +### Función Middleware validateCookies + +Finalmente, crearemos una función de middleware que valida las cookies entrantes y envía una respuesta 400 si las cookies no son válidas. + +Aquí hay una función de ejemplo que valida las cookies con un servicio externo asíncrono. + +```js +async function cookieValidator(cookies) { + try { + await externallyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Invalid cookies'); + } +} +``` + +Aquí usamos el [`cookie-parser`](/en/resources/middleware/cookie-parser) middleware para analizar las cookies entrantes del objeto `req` y pasarlas a nuestra función `cookieValidator`. El middleware `validateCookies` devuelve una Promesa que al rechazar activará automáticamente nuestro gestor de errores. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('. cookieValidator'); + +const app = express(); + +async function validateCookies(req, res, next) { + await cookieValidator(req. ookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// manejador de errores +app. se((err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Observe cómo `next()` es llamado después de `await cookieValidator(req.cookies)`. Esto asegura que si +`cookieValidator` resuelve, se llamará al siguiente middleware en la pila. Si pasas algo +a la función `next()` (excepto la cadena `'route'` o `'router'`), Express considera que la actual petición +es un error y se saltará cualquier función +que no sea de manejo de enrutamiento y middleware restante. + + + +Debido a que tiene acceso al objeto de solicitud, el objeto de respuesta, la siguiente función de middleware en la pila, y el nodo entero. s API, las posibilidades con funciones middleware son infinitas. + +Para más información sobre middleware exprés, vea: [Usando middleware exprés](/en/guide/using-middleware). + +## Middleware configurable + +Si necesita que su middleware sea configurable, exporte una función que acepte un objeto de opciones u otros parámetros, , que luego devuelve la implementación de middleware basada en los parámetros de entrada. + +Archivo: `my-middleware.js` + +```js +módulo. xports = function (options) { + return function (req, res, next) { + // Implementar la función middleware basada en el objeto de opciones + siguiente(); + }; +}; +``` + +El middleware ahora puede ser usado como se muestra a continuación. + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Consulte [cookie-session](https://github.com/expressjs/cookie-session) y [compression](https://github.com/expressjs/compression) para ver ejemplos de middleware configurable. diff --git a/src/content/docs/es/4x/starter/basic-routing.mdx b/src/content/docs/es/4x/starter/basic-routing.mdx new file mode 100644 index 0000000000..e6936dde33 --- /dev/null +++ b/src/content/docs/es/4x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Ruta básica +description: Aprenda los fundamentos de la enrutamiento en aplicaciones Express.js, incluyendo cómo definir rutas, manejar métodos HTTP y crear manejadores de rutas para su servidor web. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Enrutamiento* se refiere a determinar cómo responde una aplicación a una solicitud de cliente a un punto final en particular, que es una URI (o ruta) y un método específico de petición HTTP (GET, POST, etc.). + +Cada ruta puede tener una o más funciones manejadoras, que se ejecutan cuando la ruta es igualada. + +La definición de ruta tiene la siguiente estructura: + +```js +app.METHOD(PATH, HANDLER); +``` + +Donde: + +* `app` es una instancia de `express`. +* `METHOD` es un [método de solicitud HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), en minúsculas. +* `PATH` es una ruta en el servidor. +* `HANDLER` es la función ejecutada cuando la ruta es coincidente. + + + +This tutorial assumes that an instance of `express` named `app` is created and the server is +running. Si no estás familiarizado con la creación de una aplicación e iniciarla, consulta el Hola mundo +ejemplo. + + + +Los siguientes ejemplos ilustran la definición de rutas simples. + +Responder con `¡Hola Mundo!` en la página principal: + +```js +app.get('/', (req, res) => { + res.send('Hola Mundo!'); +}); +``` + +Responder a una solicitud POST en la ruta raíz (`/`), la página de inicio de la aplicación: + +```js +app.post('/', (req, res) => { + res.send('Obtener una solicitud POST'); +}); +``` + +Responder a una solicitud PUT a la ruta `/user`: + +```js +app.put('/user', (req, res) => { + res.send('Obtener una solicitud PUT en /user'); +}); +``` + +Responder a una solicitud DELETE a la ruta `/user`: + +```js +app.delete('/user', (req, res) => { + res.send('Obtuvo una solicitud DELETE en /user'); +}); +``` + +Para más detalles sobre enrutamiento, vea la [guía de enrutamiento](/en/guide/routing). diff --git a/src/content/docs/es/4x/starter/examples.mdx b/src/content/docs/es/4x/starter/examples.mdx new file mode 100644 index 0000000000..788006ca85 --- /dev/null +++ b/src/content/docs/es/4x/starter/examples.mdx @@ -0,0 +1,45 @@ +--- +title: Ejemplos exprés +description: Explore una colección de ejemplos de aplicaciones de Express.js que cubren varios casos de uso, integraciones y configuraciones avanzadas para ayudarle a aprender y construir sus proyectos. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Autenticación con nombre de usuario y contraseña +* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - negociación de contenido HTTP +* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Trabajando con sesiones basadas en cookies +* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Trabajando con galletas +* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transfiriendo archivos al cliente +* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Trabajando con plantillas JavaScript embebidas (ejs) +* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Creando páginas de error +* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Trabajando con middleware de error +* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Manejador de solicitudes simple +* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown como motor de plantillas +* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Trabajando con varios enrutadores Express +* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - Controladores estilo MVC +* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Tracking online user activity with `online` and `redis` packages +* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Trabajando con parámetros de ruta +* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Múltiples operaciones HTTP en el mismo recurso +* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organizar rutas usando un mapa +* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Trabajando con middleware de ruta +* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizando rutas por cada recurso +* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - API de búsqueda +* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - Sesiones de usuario +* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Subrayando archivos estáticos +* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Trabajando con hosts virtuales +* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Procesar dinámicamente las vistas +* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Saving data in request object between middleware calls +* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Servicio de API simple + +## Ejemplos adicionales + +Estos son algunos ejemplos adicionales con integraciones más amplias. + + + Esta información se refiere a sitios de terceros, productos o módulos que no son mantenidos por el equipo de + Expressjs. La lista aquí no constituye un aviso o recomendación del equipo de proyecto + Expressjs. + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Aplicación completa con Express y Next.js usando [Prisma](https://www.npmjs.com/package/prisma) como ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - API REST con Express en TypeScript usando [Prisma](https://www.npmjs.com/package/prisma) como ORM diff --git a/src/content/docs/es/4x/starter/faq.md b/src/content/docs/es/4x/starter/faq.md new file mode 100644 index 0000000000..6f808c230e --- /dev/null +++ b/src/content/docs/es/4x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: FAQ +description: Encuentre respuestas a preguntas frecuentes sobre Express.js, incluyendo temas sobre estructura de aplicaciones, modelos, autenticación, motores de plantillas, manejo de errores, y más. +--- + +## ¿Cómo debo estructurar mi aplicación? + +No hay una respuesta definitiva a esta pregunta. La respuesta depende +de la escala de tu aplicación y del equipo implicado. To be as +flexible as possible, Express makes no assumptions in terms of structure. + +Las rutas y otra lógica específica de la aplicación pueden vivir tantos archivos +como desee, en cualquier estructura de directorio que prefiera. View the following +examples for inspiration: + +- [Rutas listadas](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Mapa de ruta](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Además, existen extensiones de terceros para Express, que simplifican algunos de estos patrones: + +- [Rutas de recursos](https://github.com/expressjs/express-resource) + +## ¿Cómo defino los modelos? + +Express no tiene noción de una base de datos. Este concepto es +dejado a los módulos de Nodo de terceros, permitiéndote una interfaz +con casi cualquier base de datos. + +Vea [LoopBack](http://loopback.io) para un framework basado en Expresiones centrado en modelos. + +## ¿Cómo puedo autenticar usuarios? + +Authentication is another opinionated area that Express does not +venture into. Puede utilizar cualquier esquema de autenticación que desee. +Para un esquema simple de nombre de usuario / contraseña, vea [este ejemplo](https://github.com/expressjs/express/tree/master/examples/auth). + +## ¿Qué motores de plantillas soporta Express? + +Express soporta cualquier motor de plantillas que cumpla con la firma `(ruta, locales, callback)`. +Para normalizar las interfaces del motor de plantillas y la caché, consulte el proyecto +[consolidate.js](https://github.com/visionmedia/consolidate.js) +para obtener soporte. Los motores de plantillas no listados pueden seguir soportando la firma Express. + +Para obtener más información, consulte [Usar motores de plantilla con Express](/en/guide/using-template-engines). + +## ¿Cómo puedo manejar las respuestas 404? + +In Express, 404 responses are not the result of an error, so +the error-handler middleware will not capture them. Este comportamiento es +porque una respuesta 404 simplemente indica la ausencia de trabajo adicional por hacer; +en otras palabras, Express ha ejecutado todas las funciones y rutas de middleware, +y ha encontrado que ninguno de ellos respondió. Todo lo que necesitas hacer +es añadir una función de middleware en la parte inferior de la pila (debajo de todas las demás funciones) +para manejar una respuesta 404: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Añadir rutas dinámicamente en tiempo de ejecución en una instancia de `express.Router()` +para que las rutas no sean reemplazadas por una función de middleware. + +## ¿Cómo configuro un gestor de errores? + +Usted define middleware que maneja errores de la misma manera que otros middleware, +excepto con cuatro argumentos en lugar de tres; específicamente con la firma `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Para más información, vea [Gestión de errores] (/en/guide/error-handling). + +## ¿Cómo renderizo HTML plano? + +¡No lo tienes! No hay necesidad de "render" HTML con la función `res.render()`. +Si tienes un archivo específico, usa la función `res.sendFile()`. +Si está sirviendo muchos activos de un directorio, utilice la función de middleware `express.static()` +. + +## ¿Qué versión de Node.js requiere Express? + +- [Express 4.x](/en/4x/api) requiere 0.10 o superior de Node.js. +- [Express 5.x](/en/5x/api) requiere Node.js 18 o superior. diff --git a/src/content/docs/es/4x/starter/generator.mdx b/src/content/docs/es/4x/starter/generator.mdx new file mode 100644 index 0000000000..ef1a6d5949 --- /dev/null +++ b/src/content/docs/es/4x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Generador de aplicaciones urgente +description: Aprenda cómo utilizar la herramienta del generador de aplicaciones Express para crear rápidamente un esqueleto para sus aplicaciones Express.js, configuración de streamlining y configuración. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Utilice la herramienta generadora de aplicaciones, `express-generator`, para crear rápidamente un esqueleto de aplicación. + +Puede ejecutar el generador de aplicaciones con el comando `npx` (disponible en Node.js 8.2.0). + +```bash +$ generador de expresiones npx +``` + +Para versiones anteriores de Node, instale el generador de aplicaciones como un paquete global npm y luego ejecute: + +```bash +$ npm install -g express-generator +$ expreso +``` + +Mostrar las opciones de comando con la opción `-h`: + +```bash +$ express -h + + Uso: express [options] [dir] + + Opciones: + + -h, --help output output use information + --version output output the version number + -e, --ejs añadir soporte para motores ejs + --hbs añadir soporte para motores handlebars + --pug añadir soporte para pug engine + -H, --hogan añadir hogan. s engine soporta + --no-view generar sin el motor de vista + -v, --view add view support (ejs|hbs|hjs|jade|pug|twig|vash) (por defecto jade) + -c, --css add stylesheet support (less|Ninguno|brújula|sass) (por defecto a simple css) + --git add . itignore + -f, --force en directorio no vacío +``` + +Por ejemplo, lo siguiente crea una aplicación Express llamada *myapp*. La aplicación se creará en una carpeta llamada *myapp* en el directorio de trabajo actual y el motor de vistas se establecerá en Pug: + +```bash +$ express --view=pug myapp + + create : myapp + create : myapp/package.json + create : myapp/app. s + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index. s + crear : miapp/rutas/usuarios. s + create : myapp/public/stylesheets + create : myapp/public/stylesheets/style. ★ + create : myapp/views + create : myapp/views/index. ug + create : myapp/views/layout.pug + create : myapp/views/error. ug + create : myapp/bin + create : myapp/bin/www +``` + +Luego instale dependencias: + +```bash +$ cd myapp +$ npm install +``` + +En MacOS o Linux, ejecuta la aplicación con este comando: + +```bash +$ DEBUG=miapp:* npm inicio +``` + +En Windows Command Prompt, utilice este comando: + +```bash +> establecer DEBUG=miapp:* & npm start +``` + +En Windows PowerShell, utilice este comando: + +```bash +PS> $env:DEBUG='miapp:*'; npm start +``` + +Luego, carga `http://localhost:3000/` en tu navegador para acceder a la aplicación. + +La aplicación generada tiene la siguiente estructura de directorios: + +```bash +. +├── app.js +├── bin +│ └── www +├── package.json +├── public +│ ├── images +│ ├── javascripts +│ └── stylesheets +│ └── style.css +├── routes +│ ├── index.js +│ └── users.js +└── views + ├── error.pug + ├── index.pug + └── layout.pug + +7 directories, 9 files +``` + + + +La estructura de aplicaciones creada por el generador es sólo una de las muchas formas de estructurar aplicaciones Express. +Siéntase libre de usar esta estructura o modificarla para que se adapte mejor a sus necesidades. + + diff --git a/src/content/docs/es/4x/starter/hello-world.mdx b/src/content/docs/es/4x/starter/hello-world.mdx new file mode 100644 index 0000000000..7a005e4fa7 --- /dev/null +++ b/src/content/docs/es/4x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Hola ejemplo de mundo +description: Comienza con Express.js construyendo una sencilla aplicación 'Hola Mundo', demostrando la configuración básica y la creación de servidores para principiantes. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Incrustado a continuación es esencialmente la aplicación Express más simple que puede crear. Es una aplicación de archivo única +— *no* lo que obtendrías si utilizas el [generador Express](/en/starter/generator), que +crea el andamio para una aplicación completa con numerosos archivos JavaScript, plantillas de Jade y subdirectorios +para varios propósitos. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res. end('¡Hola Mundo!'); +}); + +app.listen(port, () => { + console.log(`Ejemplo de aplicación escuchando en el puerto ${port}`); +}); +``` + +Esta aplicación inicia un servidor y escucha en el puerto 3000 para las conexiones. La aplicación responde con "¡Hola Mundo!" para las solicitudes +a la URL raíz (`/`) o *route*. Por cada otro camino, responderá con un **404 No Encontrado**. + +## Ejecutar localmente + +Primero cree un directorio llamado `myapp`, cámbielo y ejecute `npm init`. Luego, instala `express` como una dependencia, según la [guía de instalación](/en/starter/installing). + +En el directorio `myapp`, crea un archivo llamado `app.js` y copia el código del ejemplo anterior. + + + +El `req` (petición) y `res` (respuesta) son los mismos objetos exactos que el Node proporciona, así que puedes +invocar `req. ipe()`, `req.on('data', callback)`, y cualquier otra cosa que hagas sin Express +involucradas. + + + +Ejecutar la aplicación con el siguiente comando: + +```bash +$ node app.js +``` + +Luego, carga `http://localhost:3000/` en un navegador para ver la salida. diff --git a/src/content/docs/es/4x/starter/installing.mdx b/src/content/docs/es/4x/starter/installing.mdx new file mode 100644 index 0000000000..666c03bc8d --- /dev/null +++ b/src/content/docs/es/4x/starter/installing.mdx @@ -0,0 +1,50 @@ +--- +title: Instalando +description: Aprenda cómo instalar Express.js en su entorno Node.js, incluyendo la configuración del directorio de su proyecto y la gestión de dependencias con npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Antes de comenzar, asegúrese de que tiene instalado [Node.js](https://nodejs.org/) 0.10 o superior. Luego, crea un directorio para tu aplicación y navega por ella. + +```bash +mkdir myapp +cd myapp +``` + +Usa el comando `npm init` para crear un archivo `package.json` para tu aplicación. +Para más información sobre el funcionamiento de `package.json`, consulta [Especificaciones del manejo de package.json de npm](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +Este comando te pide varias cosas, como el nombre y la versión de tu aplicación. +Por ahora, puede simplemente pulsar RETURN para aceptar los valores predeterminados para la mayoría de ellos, con la siguiente excepción: + +``` +punto de entrada: (index.js) +``` + +Introduzca `app.js`, o lo que quiera que sea el nombre del archivo principal. Si desea que sea `index.js`, pulse RETURN para aceptar el nombre de archivo predeterminado sugerido. + +Ahora, instale Express en el directorio `myapp` y guárdelo en la lista de dependencias. Por ejemplo: + +```bash +npm instalar Express +``` + +Para instalar Express temporalmente y no añadirlo a la lista de dependencias: + +```bash +npm install express --no-save +``` + + + +By default with version npm 5.0+, `npm install` adds the module to the `dependencies` list in the +`package.json` file; with earlier versions of npm, you must specify the `--save` option +explicitly. Luego, después, ejecutar `npm install` en el directorio de aplicaciones automáticamente +instalará módulos en la lista de dependencias. + + diff --git a/src/content/docs/es/4x/starter/static-files.mdx b/src/content/docs/es/4x/starter/static-files.mdx new file mode 100644 index 0000000000..a614730632 --- /dev/null +++ b/src/content/docs/es/4x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Comprobando archivos estáticos en Express +description: Describa cómo servir archivos estáticos como imágenes, CSS y JavaScript en aplicaciones Express.js usando el middleware 'static' incorporado. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Para servir archivos estáticos como imágenes, archivos CSS, y archivos JavaScript, utiliza la función middleware integrada `express.static` en Express. + +La firma de la función es: + +```js +express.static(root, [options]); +``` + +El argumento `root` especifica el directorio raíz desde el cual servir activos estáticos. +Para más información sobre el argumento `options`, vea [express.static](/en/5x/api#express.static). + +Por ejemplo, utiliza el siguiente código para servir imágenes, archivos CSS y archivos JavaScript en un directorio llamado `public`: + +```js +app.use(express.static('public')); +``` + +Ahora, puedes cargar los archivos que están en el directorio `public`: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express busca los archivos relativos al directorio estático, por lo que el nombre del directorio estático +no es parte de la URL. + + + +Para usar múltiples directorios de activos estáticos, llama a la función middleware `express.static` varias veces: + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express busca los archivos en el orden en el que estableces los directorios estáticos con la función de middleware `express.static`. + + + +Para obtener mejores resultados, usa un proxy +inverso caché para mejorar el rendimiento de +sirviendo activos estáticos. + + + +Para crear un prefijo de ruta virtual (donde la ruta no existe en el sistema de archivos) para archivos que son servidos por el `express. función tatic`, [especificar una ruta de montaje](/en/5x/api#app.use) para el directorio estático, como se muestra a continuación: + +```js +app.use('/static', express.static('public')); +``` + +Ahora, puedes cargar los archivos que están en el directorio `public` desde el prefijo de ruta `/static`. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +Sin embargo, la ruta que proporcionas a la función `express.static` es relativa al directorio desde el cual inicias tu proceso `node`. Si ejecuta la aplicación expresa desde otro directorio, es más seguro utilizar la ruta absoluta del directorio que desea servir: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public'))); +``` + +Para más detalles sobre la función `serve-static` y sus opciones, vea [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/es/5x/advanced/developing-template-engines.md b/src/content/docs/es/5x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..39a63bd5b5 --- /dev/null +++ b/src/content/docs/es/5x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Desarrollar motores de plantillas para Express +description: Aprenda cómo desarrollar motores de plantillas personalizados para Express.js usando app.engine(), con ejemplos de creación e integración de su propia lógica de renderizado de plantillas. +--- + +Usa el método `app.engine(ext, callback)` para crear tu propio motor de plantillas. `ext` se refiere a la extensión del archivo, y `callback` es la función del motor de plantilla, que acepta los siguientes elementos como parámetros: la ubicación del archivo, el objeto de opciones y la función de devolución de llamada. + +El siguiente código es un ejemplo de implementación de un motor de plantillas muy simple para renderizar archivos `.ntl`. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +Tu aplicación ahora será capaz de procesar archivos `.ntl`. Crea un archivo llamado `index.ntl` en el directorio `views` con el siguiente contenido. + +```pug +#title# +#message# +``` + +Luego, crea la siguiente ruta en tu aplicación. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +Cuando hagas una solicitud a la página de inicio, `index.ntl` será renderizado como HTML. diff --git a/src/content/docs/es/5x/guide/behind-proxies.mdx b/src/content/docs/es/5x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..ec6a8e1c11 --- /dev/null +++ b/src/content/docs/es/5x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Expresar detrás de proxies +description: Aprenda cómo configurar las aplicaciones Express.js para que funcionen correctamente detrás de los proxies inversos, incluyendo el uso de la configuración del proxy de confianza para manejar las direcciones IP del cliente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Cuando se ejecuta una aplicación Express detrás de un proxy inverso, algunas de las APIs Express pueden devolver valores diferentes de los esperados. Para ajustarse a esto, la configuración de la aplicación `trust proxy` puede utilizarse para exponer la información proporcionada por el proxy inverso en las APIs Express. El problema más común son las APIs expresas que exponen la dirección IP del cliente pueden mostrar una dirección IP interna del proxy inverso. + + + +Al configurar la configuración del `proxy de confianza`, es importante entender la configuración exacta del proxy inverso +. Dado que esta configuración confiará en los valores proporcionados en la solicitud, es importante que +la combinación de la configuración en Express coincida con cómo funciona el proxy inverso. + + + +El ajuste de la aplicación `proxy de confianza` puede establecerse en uno de los valores listados en la siguiente tabla. + + + + + + + + + + + + + + + + + + + + + +
EscribaValor
Boolean +Si es `true`, la dirección IP del cliente se entiende como la entrada más a la izquierda en la cabecera `X-Forwarded-For`. + +Si es `false`, la aplicación se entiende como directamente frente al cliente y la dirección IP del cliente se deriva de `req.socket.remoteAddress`. Esta es la configuración por defecto. + + +Cuando se establece en `true`, es importante asegurarse de que el último proxy inverso en el que se confía es eliminar/sobrescribir todas las siguientes cabeceras HTTP: `X-Forwarded-For`, `X-Forwarded-Host`, y `X-Forwarded-Proto`, de lo contrario puede ser posible que el cliente proporcione cualquier valor. + +
direcciones IP +Una dirección IP, subred, o un array de direcciones IP y subredes en las que confiar como un proxy inverso. La siguiente lista muestra los nombres de subred preconfigurados: + +* bucle atrás - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +Puede establecer direcciones IP de cualquiera de las siguientes maneras: + +```js +app.set('trust proxy', 'loopback'); // especificar una única subred +app.set('trust proxy', 'loopback, 123.123.123.123'); // especificar una subred y una dirección +app. et('trust proxy', 'loopback, linklocal, uniquelocal'); // especifica múltiples subredes como CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // especifica múltiples subredes como un array +``` + +Cuando se especifica, las direcciones IP o las subredes están excluidas del proceso de determinación de direcciones, y la dirección IP no confiable más cercana al servidor de aplicaciones se determina como la dirección IP del cliente. Esto funciona comprobando si `req.socket.remoteAddress` es de confianza. Si es así, entonces cada dirección en `X-Forwarded-For` se marca de derecha a izquierda hasta la primera dirección no confiable. + +
Número +Utilice la dirección que es como máximo el número de saltos `n` de la aplicación Express. `req.socket.remoteAddress` es la primera salida, y el resto son buscados en la cabecera `X-Forwarded-For` de derecha a izquierda. Un valor de `0` significa que la primera dirección no confiable sería `req.socket.remoteAddress`, es decir, no hay proxy inverso. + + +Al usar esta configuración, es importante asegurarse de que no hay múltiplos, rutas de longitud diferente a la aplicación Express tal que el cliente puede ser menor que el número de saltos configurados de lo contrario es posible que el cliente proporcione cualquier valor. + +
Función +Implementación de confianza personalizada. + +```js +app.set('confiar en proxy', (ip) => { + if (ip === '127.0.0.1' || ip === '123.123.123. 23') + return true; // Iders confiables + else return false; +}); +``` + +
+ +Habilitar `proxy de confianza` tendrá el siguiente impacto: + +
    +
  • + El valor de [req.hostname](/en/api#req.hostname) se deriva del valor establecido en la cabecera + `X-Forwarded-Host`, que puede ser definido por el cliente o por el proxy. +
    • +
  • + `X-Forwarded-Proto` puede ser establecido por el proxy inverso para decirle a la aplicación si es `https` o + `http` o incluso un nombre inválido. Este valor se refleja en [req.protocol](/en/api#req.protocol). +
    • +
  • + Los valores [req.ip](/en/api#req.ip) y [req.ips](/en/api#req.ips) son poblados según la dirección del socket + y la cabecera `X-Forwarded-For`, comenzando en la primera dirección no confiable. +
    • +
+ +La configuración `trust proxy` se implementa usando el paquete [proxy-addr](https://www.npmjs.com/package/proxy-addr). Para obtener más información, consulte su documentación. diff --git a/src/content/docs/es/5x/guide/debugging.mdx b/src/content/docs/es/5x/guide/debugging.mdx new file mode 100644 index 0000000000..18a5f950b2 --- /dev/null +++ b/src/content/docs/es/5x/guide/debugging.mdx @@ -0,0 +1,123 @@ +--- +title: Depuración Express +description: Aprenda cómo habilitar y utilizar los registros de depuración en aplicaciones Express.js configurando la variable de entorno DEBUG para solucionar problemas mejorados. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Para ver todos los registros internos usados en Express, establece la variable de entorno `DEBUG` a +`express:*` al ejecutar tu aplicación. + +```bash +$ DEBUG=express:* nodo index.js +``` + +En Windows, utilice el comando correspondiente. + +```bash +> $env:DEBUG = "express:*"; nodo index.js +``` + +Ejecutando este comando en la aplicación predeterminada generada por el [generador expreso](/en/starter/generator) imprime la siguiente salida: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +Cuando se hace una solicitud a la aplicación, verá los registros especificados en el código Express: + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index.pug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +Para ver los registros sólo desde la implementación del router, establece el valor de `DEBUG` a `express:router`. De la misma manera, para ver los registros sólo desde la implementación de la aplicación, establece el valor de `DEBUG` a `express:application`, y así sucesivamente. + +## Aplicaciones generadas por `express` + +Una aplicación generada por el comando `express` utiliza el módulo `debug` y su espacio de nombres de depuración está cubierto por el nombre de la aplicación. + +Por ejemplo, si generaste la aplicación con \`$ muestra expresa, puedes habilitar las declaraciones de depuración con el siguiente comando: + +```bash +$ DEBUG=sample-app:* nodo ./bin/www +``` + +Puede especificar más de un espacio de nombres de depuración asignando una lista de nombres separados por comas: + +```bash +$ DEBUG=http,mail,express:* nodo index.js +``` + +## Opciones avanzadas + +Cuando se ejecuta a través de Node.js, puede establecer algunas variables de entorno que cambiarán el comportamiento del registro de depuración: + +| Nombre | Propósito | +| ------------------- | --------------------------------------------------------------------- | +| `DEBUG` | Habilita o deshabilita espacios de nombres específicos de depuración. | +| `DEBUG_COLORS` | Usar o no colores en la salida de depuración. | +| `DEBUG_DEPTH` | Profundidad de inspección de objetos. | +| `DEBUG_FD` | Descriptor de archivo en el que escribir salida de depuración. | +| `DEBUG_SHOW_HIDDEN` | Muestra propiedades ocultas en los objetos esperados. | + + + +Las variables de entorno que empiezan con `DEBUG_` acaban siendo convertidas en un objeto Options +que se usa con formateadores `%o`/`%O. Vea la documentación de Node.js para [`util.inspect()\`](https://nodejs.org/api/util#util_util_inspect_object_options) para la lista completa +. + + diff --git a/src/content/docs/es/5x/guide/error-handling.mdx b/src/content/docs/es/5x/guide/error-handling.mdx new file mode 100644 index 0000000000..c109279842 --- /dev/null +++ b/src/content/docs/es/5x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Manejo de errores +description: Descargue cómo Express.js maneja errores en código sincrónico y asíncrono, y aprenda a implementar middleware de manejo de errores personalizado para sus aplicaciones. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Error Handling* refers to how Express catches and processes errors that +occur both synchronously and asynchronously. Express viene con un manejador de error predeterminado +, así que no necesitas escribir el tuyo propio para empezar. + +## Errores de captura + +Es importante asegurarse de que Express capture todos los errores que ocurren mientras +ejecuta los manejadores de rutas y el middleware. + +Los errores que ocurren en el código sincrónico dentro de los manejadores de rutas y middleware +no requieren trabajo extra. Si el código sincrónico arroja un error, entonces Express hará +capturarlo y procesarlo. Por ejemplo: + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Express capturará esto por su cuenta. +}); +``` + +Para los errores devueltos por funciones asincrónicas invocadas por los manejadores de rutas +y middleware, debes pasarlos a la función `next()`, donde Express las capturará y procesará +. Por ejemplo: + +```js +app.get('/', (req, res, next) => { + fs. eadFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Pasar los errores a Express. + } else { + res. end(data); + } + }); +}); +``` + +A partir de Express 5, manejadores de rutas y middleware que devuelven una Promise +llamará automáticamente a `next(value)` cuando rechacen o lancen un error. +Por ejemplo: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = await getUserById(req.params.id); + res.send(user); +}); +``` + +Si `getUserById` arroja un error o rechaza, `next` será llamado con +el error arrojado o el valor rechazado. Si no se proporciona ningún valor rechazado, `next` +será llamado con un objeto de Error predeterminado proporcionado por el enrutador Express. + +If you pass anything to the `next()` function (except the string `'route'`), +Express regards the current request as being an error and will skip any +remaining non-error handling routing and middleware functions. + +Si la devolución de llamada en una secuencia no proporciona datos, sólo errores, puede simplificar +este código de la siguiente manera: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +En el ejemplo anterior, `next` es proporcionado como el callback para `fs.writeFile`, +que es llamado con o sin errores. Si no hay error, se ejecuta el segundo manejador +, de lo contrario Express catches y procesa el error. + +Debe capturar errores que ocurren en código asíncrono invocado por manejadores de ruta o un middleware +y pasarlos a Express para su procesamiento. Por ejemplo: + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + next(err); + } + }, 100); +}); +``` + +El ejemplo anterior utiliza un bloque `try...catch` para capturar errores en el código asincrónico +y pasarlos a Express. Si el bloque `try...catch` +fuera omitido, Express no capturaría el error ya que no es parte del código de manejador +sincrónico. + +Usa promesas para evitar la sobrecarga del bloque "intentar...atrapar" o al usar funciones +que devuelven promesas. Por ejemplo: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + . hen(() => { + throw new Error('BROKEN'); + }) + . atch(next); // Los errores se pasarán a Express. +}); +``` + +Since promises automatically catch both synchronous errors and rejected promises, +you can simply provide `next` as the final catch handler and Express will catch errors, +because the catch handler is given the error as the first argument. + +También podría utilizar una cadena de manejadores para depender de la captura de errores sincrónicos +, reduciendo el código asincrónico a algo trivial. Por ejemplo: + +```js +app.get('/', [ + function (req, res, next) { + fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals. ata = data; + siguiente(err); + }); + }, + function (req, res) { + res. ocals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +El ejemplo anterior tiene un par de declaraciones triviales de la llamada `readFile` +. Si `readFile` causa un error, entonces pasa el error a Express, de lo contrario +regresa rápidamente al mundo del manejo sincrónico de errores en el siguiente manejador +en la cadena. Luego, el ejemplo anterior intenta procesar los datos. Si esto falla, entonces el gestor de errores sincrónico +lo capturará. Si hubiera hecho este procesamiento dentro de +el callback `readFile`, entonces la aplicación podría salir y los manejadores de error Express +no se ejecutarían. + +Whichever method you use, if you want Express error handlers to be called in and the +application to survive, you must ensure that Express receives the error. + +## El gestor de errores por defecto + +Express viene con un gestor de errores integrado que se encarga de cualquier error que pueda encontrarse en la aplicación. Esta función middleware por defecto se añade al final de la pila de funciones de middleware. + +Si pasas un error a `next()` y no lo gestionas en un controlador +error personalizado, será manejado por el gestor de errores integrado; el error será +escrito al cliente con el stack trace. El stack trace no está incluido +en el entorno de producción. + + + +Establece la variable de entorno `NODE_ENV` a `production`, para ejecutar la aplicación en el modo de producción. + + + +When an error is written, the following information is added to the +response: + +* El `res.statusCode` se establece desde `err.status` (o `err.statusCode`). Si + este valor está fuera del rango 4xx o 5xx, se establecerá a 500. +* El `res.statusMessage` se establece de acuerdo al código de estado. +* El cuerpo será el HTML del mensaje del código de estado cuando en el entorno + de producción, de lo contrario será `err.stack`. +* Cualquier cabecera especificada en un objeto `err.headers`. + +Si llama a `next()` con un error después de haber comenzado a escribir la respuesta +(por ejemplo, si encuentras un error al transmitir la respuesta +al cliente), el gestor de errores Express por defecto cierra la conexión +y falla la solicitud. + +Así que cuando añada un manejador de errores personalizado, debe delegar a +el manejador de errores predeterminado Express cuando los encabezados +ya han sido enviados al cliente: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Tenga en cuenta que el manejador de errores por defecto puede activarse si llama a `next()` con un error +en su código más de una vez, incluso si el middleware está configurado para manejar errores personalizados. + +Otro middleware de manejo de error se puede encontrar en [Express middleware](/en/resources/middleware). + +## Manejadores de errores escritos + +Define las funciones de middleware de la misma manera que otras funciones de middleware, +excepto las funciones de manejo de errores tienen cuatro argumentos en lugar de tres: +`(err, req, res, next)`. Por ejemplo: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Usted define middleware manejado por errores últimamente, después de otras `app.use()` y llamadas de rutas; por ejemplo: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser. rlencoded({ + extendido: true, + }) +); +app.use(bodyParser.json()); +app. se(methodOverride()); +app.use((err, req, res, next) => { + // lógica +}); +``` + +Las respuestas desde dentro de una función middleware pueden estar en cualquier formato, como una página de error HTML, un mensaje simple, o una cadena JSON. + +For organizational (and higher-level framework) purposes, you can define +several error-handling middleware functions, much as you would with +regular middleware functions. Por ejemplo, para definir un manejador de errores +para las solicitudes realizadas usando `XHR` y las que no tienen: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app. se( + bodyParser.urlencoded({ + extendido: true, + }) +); +app. se(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +En este ejemplo, el genérico `logErrors` podría escribir una solicitud y +información de error a `stderr`, por ejemplo: + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +También en este ejemplo, `clientErrorHandler` se define de la siguiente manera; en este caso, el error se pasa explícitamente al siguiente. + +Tenga en cuenta que cuando *no* llama "siguiente" en una función de manejo de errores, usted es responsable de escribir (y terminar) la respuesta. De lo contrario, esas solicitudes se "colgarán" y no serán elegibles para la recolección de basura. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500). end({ error: 'Something failed!' }); + } else { + next(err); + } +} +``` + +Implementa la función "catch-all" `errorHandler` como sigue (por ejemplo): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +Si tiene un manejador de ruta con múltiples funciones de callback, puede utilizar el parámetro `route` para saltar al siguiente manejador de ruta. Por ejemplo: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user. asPaid) { + // continúa manejando esta solicitud + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent. ind((err, doc) => { + if (err) return next(err); + res. son(doc); + }); + } +); +``` + +En este ejemplo, el manejador `getPaidContent` se omitirá pero cualquier manejador restante en `app` para `/a_route_behind_paywall` continuaría siendo ejecutado. + + + +Las llamadas a `next()` y `next(err)` indican que el controlador actual está completo y en qué estado. +`next(err)` omitirá todos los manejadores restantes en la cadena, excepto aquellos que están configurados a +errores de manejo como se describe arriba. + + diff --git a/src/content/docs/es/5x/guide/overriding-express-api.md b/src/content/docs/es/5x/guide/overriding-express-api.md new file mode 100644 index 0000000000..9be44e70df --- /dev/null +++ b/src/content/docs/es/5x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Reemplazar la API Express +description: Descubra cómo personalizar y extender la API de Express.js reemplazando métodos y propiedades en los objetos de solicitud y respuesta usando prototipos. +--- + +La API Express consiste en varios métodos y propiedades sobre los objetos de solicitud y respuesta. Estos son heredados por prototipo. Hay dos puntos de extensión para la API Express: + +1. Los prototipos globales en `express.request` y `express.response`. +2. prototipos específicos de la aplicación en `app.request` y `app.response`. + +Alterar los prototipos globales afectará a todas las aplicaciones cargadas Express en el mismo proceso. Si se desea, las alteraciones pueden hacerse específicas de la aplicación sólo modificando los prototipos específicos de la aplicación después de crear una nueva aplicación. + +## Métodos + +Puede anular la firma y el comportamiento de los métodos existentes con los suyos, asignando una función personalizada. + +A continuación se muestra un ejemplo de anular el comportamiento de [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +La implementación anterior cambia completamente la firma original de `res.sendStatus`. Ahora acepta un código de estado, tipo de codificación, y el mensaje que se enviará al cliente. + +El método sobreescrito ahora puede utilizarse de esta manera: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## Propiedades + +Las propiedades en la API Express son tamaño: + +1. Propiedades asignadas (ej: `req.baseUrl`, `req.originalUrl`) +2. Definido como getters (ej: `req.secure`, `req.ip`) + +Dado que las propiedades de la categoría 1 se asignan dinámicamente a los objetos `request` y `response` en el contexto del ciclo actual de petición-respuesta, su comportamiento no puede ser anulado. + +Las propiedades de la categoría 2 se pueden sobrescribir usando la API Express de extensiones API. + +El siguiente código reescribe cómo se derivará el valor de `req.ip`. Ahora, simplemente devuelve el valor de la cabecera de petición `Client-IP`. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Prototipo + +Para proporcionar la API Express, los objetos de solicitud / respuesta pasados a Express (a través de `app(req, res)`, por ejemplo) necesita heredar de la misma cadena prototipo. Por defecto, esto es `http.IncomingRequest.prototype` para la solicitud y `http.ServerResponse.prototype` para la respuesta. + +A menos que sea necesario, se recomienda que esto se haga únicamente a nivel de aplicación, en lugar de a nivel global. Además, tenga cuidado de que el prototipo que se está utilizando coincida con la funcionalidad lo más cerca posible de los prototipos predeterminados. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/es/5x/guide/routing.mdx b/src/content/docs/es/5x/guide/routing.mdx new file mode 100644 index 0000000000..7735a472cf --- /dev/null +++ b/src/content/docs/es/5x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Ruta +description: Aprenda cómo definir y usar rutas en aplicaciones Express.js, incluyendo métodos de ruta, rutas de ruta, parámetros, y usando Router para rutas modulares. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* se refiere a cómo responden los extremos (URIs) de una aplicación a las peticiones del cliente. +Para una introducción al enrutamiento, consulte [Enrutamiento básico](/en/starter/basic-routing). + +Define enrutamiento usando métodos del objeto Express `app` que corresponden a métodos HTTP; +por ejemplo, `app. et()` para manejar solicitudes GET y `app.post` para manejar solicitudes POST. Para una lista completa, +vea [app.METHOD](/en/5x/api#app.METHOD). También puedes usar [app.all()](/en/5x/api#app.all) para manejar todos los métodos HTTP y [app. se()](/en/5x/api#app.use) a +especificar middleware como función de callback (Ver [Usando middleware](/en/guide/using-middleware) para más detalles). + +Estos métodos de enrutamiento especifican una función de callback (a veces llamada "funciones manejadoras") llamada cuando la aplicación recibe una petición a la ruta especificada (endpoint) y el método HTTP. En otras palabras, la aplicación "escucha" para peticiones que coinciden con el/los método(s) especificado(s), y cuando detecta una coincidencia, llama a la función de callback especificada. + +De hecho, los métodos de enrutamiento pueden tener más de una función de callback como argumentos. +Con múltiples funciones de callback, es importante proporcionar `next` como un argumento a la función de callback y luego llamar `next()` dentro del cuerpo de la función para desactivar el control +al siguiente callback. + +El siguiente código es un ejemplo de una ruta muy básica. + +```js +const express = require('express'); +const app = express(); + +// responden con "Hola mundo" cuando se hace una solicitud GET a la página de inicio +aplicación. et('/', (req, res) => { + res.send('hola mundo'); +}); +``` + +## Métodos de ruta + +Un método de ruta se deriva de uno de los métodos HTTP y se adjunta a una instancia de la clase `express`. + +El siguiente código es un ejemplo de rutas definidas para los métodos `GET` y `POST` a la raíz de la aplicación. + +```js +// Ruta del método GET +app.get('/', (req, res) => { + res. end('GET request to the homepage'); +}); + +// método POST route +app. ost('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Express soporta métodos que corresponden a todos los métodos de petición HTTP: `get`, `post`, y así sucesivamente. +Para una lista completa, vea [app.METHOD](/en/5x/api#app.METHOD). + +Hay un método especial de enrutamiento, `app.all()`, usado para cargar funciones de middleware en una ruta para *all* métodos de petición HTTP. Por ejemplo, el siguiente manejador se ejecuta para peticiones a la ruta `"/secret"` ya sea usando `GET`, `POST`, `PUT`, `DELETE`, o cualquier otro método de solicitud HTTP soportado en el [módulo http](https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Acceder a la sección secreta ...'); + next(); // pasar el control al siguiente manejador +}); +``` + +## Rutas de ruta + +Las rutas de ruta, en combinación con un método de solicitud, definen los extremos en los que se pueden realizar las solicitudes. Las rutas pueden ser cadenas, patrones de cadenas o expresiones regulares. + + + +En expreso 5, los caracteres `? , `+`, `\*`, `[]`, y `()\` son manejados de manera diferente que en la versión +4, por favor revisa la [guía de migración](/en/guide/migrating-5#path-syntax) para más información. + + + + + +En expreso 4, los caracteres de expresión regular como `$` necesitan ser escapados con un `\`. + + + + + +Express usa [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) para emparejar las rutas de la ruta +; vea la documentación de la ruta a regexp para todas las posibilidades de definir rutas de la ruta. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) is a handy tool for +testing basic Express routes, although it does not support pattern matching. + + + +Las cadenas de consulta no son parte de la ruta de la ruta. + +### Rutas de ruta basadas en cadenas + +Esta ruta coincidirá con las peticiones a la ruta raíz, `/`. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +Esta ruta coincidirá con las peticiones a `/about`. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +Esta ruta de ruta coincidirá con peticiones a `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Rutas de ruta basadas en patrones de cadenas + + + +Los patrones de cadenas en Express 5 ya no funcionan. Consulte la guía de migración + para obtener más información. + + + +Esta ruta de ruta coincidirá con `acd` y `abcd`. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +Esta ruta coincidirá con `abcd`, `abbcd`, `abbbcd`, y así sucesivamente. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +Esta ruta de ruta coincidirá con `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd`, y así sucesivamente. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +Esta ruta coincidirá con `/abe` y `/abcde`. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Rutas de ruta basadas en expresiones regulares + +Esta ruta coincidirá con cualquier cosa con una "a". + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +Esta ruta coincidirá con `butterfly` y `dragonfly`, pero no `butterflyman`, `dragonflyman`, y así sucesivamente. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Parámetros de ruta + +Los parámetros de ruta se llaman segmentos de URL que se utilizan para capturar los valores especificados en su posición en la URL. Los valores capturados son poblados en el objeto `req.params`, con el nombre del parámetro de ruta especificado en la ruta como sus claves respectivas. + +``` +Ruta de ruta: /users/:userId/books/:bookId +URL de petición: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +Para definir rutas con parámetros de ruta, simplemente especifique los parámetros de ruta en la ruta como se muestra a continuación. + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +El nombre de los parámetros de la ruta debe estar compuesto de "caracteres de palabra" ([A-Za-z0-9_]). + + + +Dado que los guiones (`-`) y el punto (`.`) se interpretan literalmente, pueden ser utilizados junto con parámetros de ruta para propósitos útiles. + +``` +Ruta de ruta: /flights/:from-:to +Request URL: http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Ruta de ruta: /plantae/:genus.:species +Request URL: http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +En expreso 5, no se admiten caracteres de expresión regular en rutas para más información, por favor +consulte la [guía de migración](/en/guide/migrating-5#path-syntax). + + + +Para tener más control sobre la cadena exacta que puede coincidir con un parámetro de ruta, puede añadir una expresión regular entre paréntesis (`()`): + +``` +Ruta de ruta: /user/:userId(\d+) +URL de Solicitud: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Debido a que la expresión regular es generalmente parte de una cadena literal, Asegúrate de escapar cualquier `\` +caracteres con una barra inversa adicional, por ejemplo `\d+`. + + + + +En Express 4.x, el carácter `*` en expresiones regulares no se interpreta de la forma habitual. Como un workaround, usa `{0,}` en lugar de `*`. Es probable que esto se arregle en Express 5. + + +## Manejadores de rutas + +Puedes proporcionar múltiples funciones de callback que se comportan como [middleware](/en/guide/using-middleware) para gestionar una solicitud. La única excepción es que estos callbacks podrían invocar a `next('route')` para evitar las llamadas restantes de ruta. Se puede utilizar este mecanismo para imponer condiciones previas a una ruta, luego pasar el control a las rutas posteriores si no hay razón para proceder con la ruta actual. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params. d === '0') { + return next('route'); + } + res. end(`Usuario ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Controlador especial para el usuario ID 0'); +}); +``` + +En este ejemplo: + +* `GET /user/5` → manejado por primera ruta → envía "Usuario 5" +* `GET /user/0` → primera ruta llama a `next('ruta')`, saltando a la siguiente ruta `/user/:id` + +Los manejadores de rutas pueden ser en forma de una función, un array de funciones o combinaciones de ambos, como se muestra en los siguientes ejemplos. + +Una única función de callback puede manejar una ruta. Por ejemplo: + +```js +app.get('/example/a', (req, res) => { + res.send('Hola de A!'); +}); +``` + +Más de una función de callback puede manejar una ruta (asegúrese de especificar el objeto `siguiente`). Por ejemplo: + +```js +app.get( + '/example/b', + (req, res, next) => { + consola. og('la respuesta será enviada por la siguiente función . .'); + siguiente(); + }, + (req, res) => { + res. end('Hola de B!'); + } +); +``` + +Una matriz de funciones de callback puede manejar una ruta. Por ejemplo: + +```js +const cb0 = function (req, res, next) { + consola. og('CB0'); + siguiente(); +}; + +const cb1 = function (req, res, next) { + consola. og('CB1'); + siguiente(); +}; + +const cb2 = function (req, res) { + res. end('Hola de C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +Una combinación de funciones independientes y arreglos de funciones puede manejar una ruta. Por ejemplo: + +```js +const cb0 = function (req, res, next) { + consola. og('CB0'); + siguiente(); +}; + +const cb1 = function (req, res, next) { + consola. og('CB1'); + siguiente(); +}; + +app. et( + '/example/d', + [cb0, cb1], + (req, res, next) => { + consola. og('la respuesta será enviada por la siguiente función . .'); + siguiente(); + }, + (req, res) => { + res. end('Hola de D!'); + } +); +``` + +## Métodos de respuesta + +Los métodos en el objeto de respuesta (`res`) en la siguiente tabla pueden enviar una respuesta al cliente y terminar el ciclo de solicitud y respuesta. Si ninguno de estos métodos es llamado desde un gestor de rutas, la petición del cliente se dejará colgada. + +| Método | Descripción | +| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | Solicitar un archivo para ser descargado. | +| [res.end()](/en/5x/api#res.end) | Terminar el proceso de respuesta. | +| [res.json()](/en/5x/api#res.json) | Enviar una respuesta JSON. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Envía una respuesta JSON con soporte JSONP. | +| [res.redirect()](/en/5x/api#res.redirect) | Redirigir una solicitud. | +| [res.render()](/en/5x/api#res.render) | Procesar una plantilla de vista. | +| [res.send()](/en/5x/api#res.send) | Enviar una respuesta de varios tipos. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Enviar un archivo como un flujo de octet. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Establece el código de estado de respuesta y envía su representación de cadena como el cuerpo de respuesta. | + +## app.route() + +Puede crear manejadores de rutas encadenables para una ruta usando `app.route()`. +Debido a que la ruta se especifica en una única ubicación, la creación de rutas modulares es útil, al igual que la reducción de redundancia y tipografías. Para más información sobre rutas, vea: [documentación Router() ](/en/5x/api#router). + +Aquí hay un ejemplo de manejadores encadenados de rutas que se definen usando `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res. end('Obtén un libro al azar'); + }) + . ost((req, res) => { + res.send('Agregar un libro'); + }) + . ut((req, res) => { + res.send('Actualizar el libro'); +}); +``` + +## express.Router + +Utilice la clase `express.Router` para crear manejadores modulares de rutas. Una instancia de `Router` es un sistema completo de middleware y enrutamiento; por esta razón, a menudo se le denomina "mini-app". + +El siguiente ejemplo crea un router como módulo, carga una función de middleware en él, define algunas rutas y monta el módulo del router en una ruta de la aplicación principal. + +Crea un archivo de enrutador llamado `birds.js` en el directorio de la aplicación, con el siguiente contenido: + +```js +const express = require('express'); +const router = express. outer(); + +// middleware que es específico para este router +const timeLog = (req, res, next) => { + consola. og('Hora: ', Date.now()); + siguiente(); +}; enrutador +. se(timeLog); + +// define la ruta de la página de inicio +router.get('/', (req, res) => { + res. end('Página de inicio de aves'); +}); +// define la ruta +router. et('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Luego, cargue el módulo de enrutador en la aplicación: + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +La aplicación ahora será capaz de manejar solicitudes a `/birds` y `/birds/about`, así como llamar a la función de middleware `timeLog` que es específica de la ruta. + +Pero si la ruta padre `/birds` tiene parámetros de ruta, no será accesible por defecto desde las subrutas. Para hacerlo accesible, necesitarás pasar la opción `mergeParams` al constructor de Router [reference](/en/5x/api#app.use). + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/es/5x/guide/using-middleware.mdx b/src/content/docs/es/5x/guide/using-middleware.mdx new file mode 100644 index 0000000000..07d3417df7 --- /dev/null +++ b/src/content/docs/es/5x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Usando middleware +description: Aprenda cómo usar middleware en aplicaciones Express.js, incluyendo middleware de nivel de aplicación y router, manejo de errores, e integración de middleware de terceros. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express es un framework web de enrutamiento y middleware que tiene una funcionalidad mínima propia: Una aplicación Express es esencialmente una serie de llamadas a funciones de middleware. + +Las funciones *Middleware* son funciones que tienen acceso al [objeto de solicitud](/en/5x/api#req) (`req`), el [objeto de respuesta](/en/5x/api#res) (`res`), y la siguiente función de middleware en el ciclo de solicitud y respuesta de la aplicación. La siguiente función middleware se denota comúnmente por una variable llamada `next`. + +Las funciones de Middleware pueden realizar las siguientes tareas: + +* Ejecutar cualquier código. +* Realizar cambios en la solicitud y en los objetos de respuesta. +* Terminar el ciclo de solicitud de respuesta. +* Llame a la siguiente función de middleware en la pila. + +Si la función actual de middleware no termina el ciclo de solicitud de respuesta, debe llamar a `next()` para pasar el control a la siguiente función de middleware. De lo contrario, la solicitud quedará colgada. + +Una aplicación Express puede utilizar los siguientes tipos de middleware: + +* [Middleware de nivel de aplicación](#middleware.application) +* [Middleware de nivel superior](#middleware.router) +* [Middleware de manejo de errores](#middleware.error-handling) +* [Middleware incorporado](#middleware.built-in) +* [Middleware de terceros](#middleware.third-party) + +Puede cargar middleware de nivel de aplicación y de enrutador con una ruta de montaje opcional. +También puede cargar una serie de funciones de middleware juntas, lo que crea un substack del sistema de middleware en un punto de montaje. + +## Middleware de nivel de aplicación + +Vincular middleware a una instancia del [objeto de aplicación](/en/5x/api#app) usando `app.use()` y `app. ETHOD()` funciona, donde `METHOD` es el método HTTP de la petición que la función middleware maneja (como GET, PUT o POST) en minúsculas. + +Este ejemplo muestra una función de middleware sin ruta de montaje. La función se ejecuta cada vez que la aplicación recibe una solicitud. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +Este ejemplo muestra una función middleware montada en la ruta `/user/:id`. La función se ejecuta para cualquier tipo de petición +HTTP en la ruta `/user/:id`. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +Este ejemplo muestra una ruta y su función manejadora (middleware system). La función maneja peticiones GET a la ruta `/user/:id`. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USUARIO'); +}); +``` + +He aquí un ejemplo de carga de una serie de funciones de middleware en un punto de montaje, con una ruta de montaje. +Ilustra un substack de middleware que imprime la información de la petición para cualquier tipo de petición HTTP a la ruta `/user/:id`. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + consola. og('Tipo de solicitud:', req.method); + siguiente(); + } +); +``` + +Los manejadores de rutas le permiten definir múltiples rutas para una ruta. El siguiente ejemplo define dos rutas para peticiones GET a la ruta `/user/:id`. La segunda ruta no causará ningún problema, pero nunca se llamará porque la primera ruta termina el ciclo de solicitud de respuesta. + +Este ejemplo muestra un substack de middleware que maneja peticiones GET a la ruta `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req. arams.id); + siguiente(); + }, + (req, res, next) => { + res. end('Información de usuario'); + } +); + +// manejador para la ruta /user/:id, que imprime el ID de usuario +app. et('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +Para omitir el resto de las funciones de middleware desde una pila de middleware de router, llame a `next('ruta')` para pasar el control a la siguiente ruta. + + + +`next('ruta')` solo funcionará en funciones de middleware que fueron cargadas usando las funciones +`app.METHOD()` o `router.METHOD()`. + + + +Este ejemplo muestra un substack de middleware que maneja peticiones GET a la ruta `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + // si el ID de usuario es 0, saltar a la siguiente ruta + si (req. aramas. d === '0') siguiente('ruta'); + // de lo contrario pasa el control a la siguiente función de middleware en esta pila + si no siguiente(); + }, + (req, res, next) => { + // envía una respuesta regular + res. end('regular'); + } +); + +// manejador para la ruta /user/:id, que envía una respuesta especial +app. et('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +Middleware también puede ser declarado en una matriz para reusabilidad. + +Este ejemplo muestra una matriz con un substack de middleware que maneja peticiones GET en la ruta `/user/:id` + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req. riginalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Request Type:', req. ethod); + siguiente(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app. et('/user/:id', logStuff, (req, res, next) => { + res.send('Información de usuario'); +}); +``` + +## Middleware de nivel remoto + +El middleware Router-level funciona de la misma manera que el middleware a nivel de aplicación, excepto que está vinculado a una instancia de `express.Router()`. + +```js +const router = express.Router(); +``` + +Carga el middleware a nivel de enrutador usando las funciones `router.use()` y `router.METHOD()`. + +El siguiente código de ejemplo replica el sistema middleware que se muestra arriba para el middleware de nivel de aplicación, mediante el uso de router-level middleware: + +```js +const express = require('express'); +const app = express(); +const router = express. outer(); + +// una función de middleware sin ruta de montaje. Este código se ejecuta para cada petición al router +. se((req, res, next) => { + console.log('Hora:', Date. ow()); + siguiente(); +}); + +// un substack de middleware muestra información de petición para cualquier tipo de petición HTTP al router /user/:id path +. se( + '/user/:id', + (req, res, next) => { + console.log('URL de solicitud:', req. riginalUrl); + next(); + }, + (req, res, next) => { + consola. og('Tipo de solicitud:', req. ethod); + next(); + } +); + +// un substack de middleware que maneja las solicitudes GET al router /user/:id path +. et( + '/user/:id', + (req, res, next) => { + // si el ID de usuario es 0, saltar al siguiente router + if (req. aramas. d === '0') siguiente('ruta'); + // de lo contrario pasar el control a la siguiente función de middleware en esta pila + más siguiente(); + }, + (req, res, next) => { + // renderiza una página regular + res. ender('regular'); + } +); + +// manejador para la ruta /user/:id, que renderiza una página especial +router. et('/user/:id', (req, res, next) => { + consola. og(req.params.id); + res.render('special'); +}); + +// monta el router en la aplicación +app.use('/', router); +``` + +Para omitir el resto de las funciones de middleware del enrutador, llama a `next('router')` +para pasar el control de vuelta fuera de la instancia del enrutador. + +Este ejemplo muestra un substack de middleware que maneja peticiones GET a la ruta `/user/:id`. + +```js +const express = require('express'); +const app = express(); +const router = express. outer(); + +// predice el enrutador con un cheque y rescinda cuando sea necesario enrutador +. se((req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router. et('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// usa el enrutador y 401 cualquier cosa que caiga a través de +aplicación. se('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## Middleware de manejo de errores + + + +Middleware manejado por errores siempre toma *four* argumentos. Debe proporcionar cuatro argumentos para +identificarlo como una función de middleware que maneja errores. Incluso si no necesitas usar el objeto `next` +, debes especificarlo para mantener la firma. De lo contrario, el objeto `siguiente` será +interpretado como middleware regular y fallará al manejar errores. + + + +Define las funciones de middleware de la misma manera que otras funciones de middleware, excepto con cuatro argumentos en lugar de tres, específicamente con la firma `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Para más detalles sobre el middleware de manejo de errores, vea: [Gestión de errores](/en/guide/error-handling). + +## Middleware incorporado + +A partir de la versión 4.x, Express ya no depende de [Connect](https://github.com/senchalabs/connect). Las funciones +del middleware que anteriormente estaban incluidas con Express están ahora en módulos separados; vea [la lista de funciones de middleware](https://github.com/senchalabs/connect#middleware). + +Express tiene las siguientes funciones de middleware incorporadas: + +* [express.static](/en/5x/api#express.static) sirve activos estáticos como archivos HTML, imágenes, etc. +* [express.json](/en/5x/api#express.json) analiza las solicitudes entrantes con cargas útiles JSON. **NOTA: Disponible con Express 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) analiza las solicitudes entrantes con payloads codificados por URL. **NOTA: Disponible con Express 4.16.0+** + +## Middleware de terceros + +Utilice middleware de terceros para añadir funcionalidad a aplicaciones Express. + +Instale el módulo Node.js para la funcionalidad requerida, luego guárdelo en su aplicación a nivel de aplicación o a nivel de enrutador. + +El siguiente ejemplo ilustra la instalación y carga de la función middleware `cookie-parser`. + +```bash +$ npm instalar cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// cargar el middleware de análisis de cookies +app.use(cookieParser()); +``` + +Para una lista parcial de funciones de middleware de terceros que se utilizan comúnmente con Express, vea: [Middleware de terceros](../resources/middleware). diff --git a/src/content/docs/es/5x/guide/using-template-engines.mdx b/src/content/docs/es/5x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..0de07ab115 --- /dev/null +++ b/src/content/docs/es/5x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Utilizando motores de plantillas con Express +description: Descubra cómo integrar y utilizar motores de plantillas como Pug, Handlebars y EJS con Express.js para renderizar páginas HTML dinámicas eficientemente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Un *template engine* le permite usar plantillas estáticas en su aplicación. En tiempo de ejecución, el motor de plantillas reemplaza variables +en un archivo de plantilla con valores reales. y transforma la plantilla en un archivo HTML enviado al cliente. +Este enfoque facilita el diseño de una página HTML. + +El [generador de aplicaciones Express](/en/starter/generator) utiliza [Pug](https://pugjs.org/api/getting-started.html) como predeterminado, pero también soporta [Handlebars](https://www.npmjs.com/package/handlebars), y [EJS](https://www.npmjs.com/package/ejs), entre otros. + +Para renderizar archivos de plantilla, establezca las siguientes [propiedades de configuración de aplicación](/en/4x/api#app.set), en el `app.js` por defecto creado por el generador: + +* `vistas`, el directorio donde están ubicados los archivos de plantilla. Ej: `app.set('vistas', './views')`. + Esto por defecto es el directorio `views` en el directorio raíz de la aplicación. +* `ver engine`, el motor de plantillas a usar. Por ejemplo, para usar el motor de plantillas Pug: `app.set('view engine', 'pug')`. + +A continuación, instale el correspondiente paquete npm del motor de plantillas; por ejemplo para instalar Pug: + +```bash +$ npm install pug --save +``` + + +Motores de plantillas compatibles con Expresiones, tales como Pug exportar una función llamada `__express(filePath, options, callback)`, +que `res.render()` llama para renderizar el código de plantilla. + +Algunos motores de plantillas no siguen esta convención. La biblioteca [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +sigue esta convención mapeando todos los motores de plantillas populares de Node.js, y por lo tanto funciona perfectamente dentro de Express. + + + +Después de que el motor de vista esté definido, no tiene que especificar el motor o cargar el módulo de motor de plantillas en su aplicación; +Express carga el módulo internamente, por ejemplo: + +```js +app.set('ver motor', 'pug'); +``` + +Luego, crea un archivo de plantilla Pug llamado `index.pug` en el directorio `views`, con el siguiente contenido: + +```pug +html + head + title= title + body + h1= message +``` + +Crea una ruta para representar el archivo `index.pug`. Si la propiedad `view engine` no está definida, +debe especificar la extensión del archivo `view`. De lo contrario, puede omitirlo. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: '¡Hola!' }); +}); +``` + +Cuando hagas una solicitud a la página de inicio, el archivo `index.pug` será renderizado como HTML. + +La caché del motor de vistas no almacena en caché el contenido de la salida de la plantilla, sólo la misma plantilla subyacente. La vista todavía se vuelve a procesar con cada petición incluso cuando la caché está encendida. diff --git a/src/content/docs/es/5x/guide/writing-middleware.mdx b/src/content/docs/es/5x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..20e58642b6 --- /dev/null +++ b/src/content/docs/es/5x/guide/writing-middleware.mdx @@ -0,0 +1,209 @@ +--- +title: Escribiendo middleware para uso en aplicaciones Express +description: Aprenda cómo escribir funciones personalizadas de middleware para aplicaciones Express.js, incluyendo ejemplos y mejores prácticas para mejorar la gestión de peticiones y respuestas. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Las funciones *Middleware* son funciones que tienen acceso al [objeto de solicitud](/en/5x/api#req) (`req`), el [objeto de respuesta](/en/5x/api#res) (`res`), y la función `next` en el ciclo de solicitud y respuesta de la aplicación. La función `siguiente` es una función en el router Express que, cuando se invoca, ejecuta el middleware sucediendo al middleware actual. + +Las funciones de Middleware pueden realizar las siguientes tareas: + +* Ejecutar cualquier código. +* Realizar cambios en la solicitud y en los objetos de respuesta. +* Terminar el ciclo de solicitud de respuesta. +* Llama al siguiente middleware en la pila. + +Si la función actual de middleware no termina el ciclo de solicitud de respuesta, debe llamar a `next()` para pasar el control a la siguiente función de middleware. De lo contrario, la solicitud quedará colgada. + +La siguiente figura muestra los elementos de una llamada a una función de middleware: + +![Elementos de una llamada a función middleware](/images/express-mw.png) + +A partir de Express 5, las funciones de middleware que devuelven una Promise llamarán `next(value)` cuando rechacen o lancen un error. `next` será llamado con el valor rechazado o con el error arrojado. + +## Ejemplo + +He aquí un ejemplo de una simple aplicación "Hola Mundo" Express. +El resto de este artículo definirá y añadirá tres funciones de middleware a la aplicación: +una llamada `myLogger` que imprime un simple mensaje de registro, uno llamado `requestTime` que +muestra la marca de tiempo de la petición HTTP, y uno llamado `validateCookies` que valida las cookies entrantes. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('¡Hola Mundo!'); +}); + +app.listen(3000); +``` + +### Función Middleware myLogger + +Aquí hay un ejemplo simple de una función middleware llamada "myLogger". Esta función solo imprime +"LOGGED" cuando una solicitud a la aplicación pasa a través de ella. La función middleware está asignada a una variable +llamada `myLogger`. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +Tenga en cuenta la llamada anterior a `next()`. Llamar a esta función invoca la siguiente función de middleware en +la aplicación. La función `next()` no es parte del Nodo. s o Express API, pero es el tercer argumento +que se pasa a la función middleware. La función `next()` podría ser nombrada cualquier cosa, +pero por convención siempre se llama "siguiente". Para evitar la confusión, utilice siempre esta convención. + + + +Para cargar la función middleware, llama a `app.use()`, especificando la función middleware. +Por ejemplo, el siguiente código carga la función middleware `myLogger` antes de la ruta a la ruta raíz (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + consola. og('LOGGED'); + siguiente(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('¡Hola Mundo!'); +}); + +app.listen(3000); +``` + +Cada vez que la aplicación recibe una solicitud, imprime el mensaje "LOGGED" en el terminal. + +El orden de carga de middleware es importante: las funciones de middleware que se cargan primero también se ejecutan primero. + +Si `myLogger` es cargado después de la ruta a la ruta raíz, la solicitud nunca llega a ella y la aplicación no imprime "LOGGED", porque el manejador de rutas de la ruta raíz termina el ciclo de solicitud de respuesta. + +La función Middleware `myLogger` simplemente imprime un mensaje, luego pasa la solicitud a la siguiente función de middleware en la pila llamando a la función `next()`. + +### Tiempo de solicitud de la función Middleware + +A continuación, crearemos una función de middleware llamada "requestTime" y agregaremos una propiedad llamada `requestTime` +al objeto de la solicitud. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +La aplicación ahora utiliza la función de middleware `requestTime`. Además, la función de callback de la ruta raíz utiliza la propiedad que la función middleware añade a `req` (el objeto de la solicitud). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req. equestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app. et('/', (req, res) => { + let responseText = '¡Hola Mundo!
'; + responseText += `Solicitado en: ${req.requestTime}`; + res. end(responseText); +}); + +app.listen(3000); +``` + +Cuando hace una solicitud a la raíz de la aplicación, la aplicación ahora muestra la marca de tiempo de su solicitud en el navegador. + +### Función Middleware validateCookies + +Finalmente, crearemos una función de middleware que valida las cookies entrantes y envía una respuesta 400 si las cookies no son válidas. + +Aquí hay una función de ejemplo que valida las cookies con un servicio externo asíncrono. + +```js +async function cookieValidator(cookies) { + try { + await externallyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Invalid cookies'); + } +} +``` + +Aquí usamos el [`cookie-parser`](/en/resources/middleware/cookie-parser) middleware para analizar las cookies entrantes del objeto `req` y pasarlas a nuestra función `cookieValidator`. El middleware `validateCookies` devuelve una Promesa que al rechazar activará automáticamente nuestro gestor de errores. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('. cookieValidator'); + +const app = express(); + +async function validateCookies(req, res, next) { + await cookieValidator(req. ookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// manejador de errores +app. se((err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Observe cómo `next()` es llamado después de `await cookieValidator(req.cookies)`. Esto asegura que si +`cookieValidator` resuelve, se llamará al siguiente middleware en la pila. Si pasas algo +a la función `next()` (excepto la cadena `'route'` o `'router'`), Express considera que la actual petición +es un error y se saltará cualquier función +que no sea de manejo de enrutamiento y middleware restante. + + + +Debido a que tiene acceso al objeto de solicitud, el objeto de respuesta, la siguiente función de middleware en la pila, y el nodo entero. s API, las posibilidades con funciones middleware son infinitas. + +Para más información sobre middleware exprés, vea: [Usando middleware exprés](/en/guide/using-middleware). + +## Middleware configurable + +Si necesita que su middleware sea configurable, exporte una función que acepte un objeto de opciones u otros parámetros, , que luego devuelve la implementación de middleware basada en los parámetros de entrada. + +Archivo: `my-middleware.js` + +```js +módulo. xports = function (options) { + return function (req, res, next) { + // Implementar la función middleware basada en el objeto de opciones + siguiente(); + }; +}; +``` + +El middleware ahora puede ser usado como se muestra a continuación. + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Consulte [cookie-session](https://github.com/expressjs/cookie-session) y [compression](https://github.com/expressjs/compression) para ver ejemplos de middleware configurable. diff --git a/src/content/docs/es/5x/starter/basic-routing.mdx b/src/content/docs/es/5x/starter/basic-routing.mdx new file mode 100644 index 0000000000..e6936dde33 --- /dev/null +++ b/src/content/docs/es/5x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Ruta básica +description: Aprenda los fundamentos de la enrutamiento en aplicaciones Express.js, incluyendo cómo definir rutas, manejar métodos HTTP y crear manejadores de rutas para su servidor web. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Enrutamiento* se refiere a determinar cómo responde una aplicación a una solicitud de cliente a un punto final en particular, que es una URI (o ruta) y un método específico de petición HTTP (GET, POST, etc.). + +Cada ruta puede tener una o más funciones manejadoras, que se ejecutan cuando la ruta es igualada. + +La definición de ruta tiene la siguiente estructura: + +```js +app.METHOD(PATH, HANDLER); +``` + +Donde: + +* `app` es una instancia de `express`. +* `METHOD` es un [método de solicitud HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), en minúsculas. +* `PATH` es una ruta en el servidor. +* `HANDLER` es la función ejecutada cuando la ruta es coincidente. + + + +This tutorial assumes that an instance of `express` named `app` is created and the server is +running. Si no estás familiarizado con la creación de una aplicación e iniciarla, consulta el Hola mundo +ejemplo. + + + +Los siguientes ejemplos ilustran la definición de rutas simples. + +Responder con `¡Hola Mundo!` en la página principal: + +```js +app.get('/', (req, res) => { + res.send('Hola Mundo!'); +}); +``` + +Responder a una solicitud POST en la ruta raíz (`/`), la página de inicio de la aplicación: + +```js +app.post('/', (req, res) => { + res.send('Obtener una solicitud POST'); +}); +``` + +Responder a una solicitud PUT a la ruta `/user`: + +```js +app.put('/user', (req, res) => { + res.send('Obtener una solicitud PUT en /user'); +}); +``` + +Responder a una solicitud DELETE a la ruta `/user`: + +```js +app.delete('/user', (req, res) => { + res.send('Obtuvo una solicitud DELETE en /user'); +}); +``` + +Para más detalles sobre enrutamiento, vea la [guía de enrutamiento](/en/guide/routing). diff --git a/src/content/docs/es/5x/starter/examples.mdx b/src/content/docs/es/5x/starter/examples.mdx new file mode 100644 index 0000000000..6fb4611e9c --- /dev/null +++ b/src/content/docs/es/5x/starter/examples.mdx @@ -0,0 +1,49 @@ +--- +title: Ejemplos exprés +description: Explore una colección de ejemplos de aplicaciones de Express.js que cubren varios casos de uso, integraciones y configuraciones avanzadas para ayudarle a aprender y construir sus proyectos. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Esta página contiene una lista de ejemplos usando Express. + +* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Autenticación con nombre de usuario y contraseña +* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - negociación de contenido HTTP +* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Trabajando con sesiones basadas en cookies +* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Trabajando con galletas +* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transfiriendo archivos al cliente +* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Trabajando con plantillas JavaScript embebidas (ejs) +* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Creando páginas de error +* [error](https://github.com/expressjs/express/tree/master/examples/error) - Trabajando con middleware de error +* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Manejador de solicitudes simple +* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown como motor de plantillas +* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Trabajando con varios enrutadores Express +* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - Controladores estilo MVC +* [online](https://github.com/expressjs/express/tree/master/examples/online) - Tracking online user activity with `online` and `redis` packages +* [params](https://github.com/expressjs/express/tree/master/examples/params) - Trabajando con parámetros de ruta +* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Múltiples operaciones HTTP en el mismo recurso +* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organizar rutas usando un mapa +* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Trabajando con middleware de ruta +* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizando rutas por cada recurso +* [search](https://github.com/expressjs/express/tree/master/examples/search) - API de búsqueda +* [session](https://github.com/expressjs/express/tree/master/examples/session) - Sesiones de usuario +* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Subrayando archivos estáticos +* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Trabajando con hosts virtuales +* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Procesar dinámicamente las vistas +* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Saving data in request object between middleware calls +* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Servicio de API simple + +## Ejemplos adicionales + +Estos son algunos ejemplos adicionales con integraciones más amplias. + + + +Esta información se refiere a sitios de terceros, productos o módulos que no son mantenidos por el equipo de +Expressjs. La lista aquí no constituye un aviso o recomendación del equipo de proyecto +Expressjs. + + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Aplicación completa con Express y Next.js usando [Prisma](https://www.npmjs.com/package/prisma) como ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - API REST con Express en TypeScript usando [Prisma](https://www.npmjs.com/package/prisma) como ORM diff --git a/src/content/docs/es/5x/starter/faq.md b/src/content/docs/es/5x/starter/faq.md new file mode 100644 index 0000000000..6f808c230e --- /dev/null +++ b/src/content/docs/es/5x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: FAQ +description: Encuentre respuestas a preguntas frecuentes sobre Express.js, incluyendo temas sobre estructura de aplicaciones, modelos, autenticación, motores de plantillas, manejo de errores, y más. +--- + +## ¿Cómo debo estructurar mi aplicación? + +No hay una respuesta definitiva a esta pregunta. La respuesta depende +de la escala de tu aplicación y del equipo implicado. To be as +flexible as possible, Express makes no assumptions in terms of structure. + +Las rutas y otra lógica específica de la aplicación pueden vivir tantos archivos +como desee, en cualquier estructura de directorio que prefiera. View the following +examples for inspiration: + +- [Rutas listadas](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Mapa de ruta](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Además, existen extensiones de terceros para Express, que simplifican algunos de estos patrones: + +- [Rutas de recursos](https://github.com/expressjs/express-resource) + +## ¿Cómo defino los modelos? + +Express no tiene noción de una base de datos. Este concepto es +dejado a los módulos de Nodo de terceros, permitiéndote una interfaz +con casi cualquier base de datos. + +Vea [LoopBack](http://loopback.io) para un framework basado en Expresiones centrado en modelos. + +## ¿Cómo puedo autenticar usuarios? + +Authentication is another opinionated area that Express does not +venture into. Puede utilizar cualquier esquema de autenticación que desee. +Para un esquema simple de nombre de usuario / contraseña, vea [este ejemplo](https://github.com/expressjs/express/tree/master/examples/auth). + +## ¿Qué motores de plantillas soporta Express? + +Express soporta cualquier motor de plantillas que cumpla con la firma `(ruta, locales, callback)`. +Para normalizar las interfaces del motor de plantillas y la caché, consulte el proyecto +[consolidate.js](https://github.com/visionmedia/consolidate.js) +para obtener soporte. Los motores de plantillas no listados pueden seguir soportando la firma Express. + +Para obtener más información, consulte [Usar motores de plantilla con Express](/en/guide/using-template-engines). + +## ¿Cómo puedo manejar las respuestas 404? + +In Express, 404 responses are not the result of an error, so +the error-handler middleware will not capture them. Este comportamiento es +porque una respuesta 404 simplemente indica la ausencia de trabajo adicional por hacer; +en otras palabras, Express ha ejecutado todas las funciones y rutas de middleware, +y ha encontrado que ninguno de ellos respondió. Todo lo que necesitas hacer +es añadir una función de middleware en la parte inferior de la pila (debajo de todas las demás funciones) +para manejar una respuesta 404: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Añadir rutas dinámicamente en tiempo de ejecución en una instancia de `express.Router()` +para que las rutas no sean reemplazadas por una función de middleware. + +## ¿Cómo configuro un gestor de errores? + +Usted define middleware que maneja errores de la misma manera que otros middleware, +excepto con cuatro argumentos en lugar de tres; específicamente con la firma `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Para más información, vea [Gestión de errores] (/en/guide/error-handling). + +## ¿Cómo renderizo HTML plano? + +¡No lo tienes! No hay necesidad de "render" HTML con la función `res.render()`. +Si tienes un archivo específico, usa la función `res.sendFile()`. +Si está sirviendo muchos activos de un directorio, utilice la función de middleware `express.static()` +. + +## ¿Qué versión de Node.js requiere Express? + +- [Express 4.x](/en/4x/api) requiere 0.10 o superior de Node.js. +- [Express 5.x](/en/5x/api) requiere Node.js 18 o superior. diff --git a/src/content/docs/es/5x/starter/generator.mdx b/src/content/docs/es/5x/starter/generator.mdx new file mode 100644 index 0000000000..ef1a6d5949 --- /dev/null +++ b/src/content/docs/es/5x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Generador de aplicaciones urgente +description: Aprenda cómo utilizar la herramienta del generador de aplicaciones Express para crear rápidamente un esqueleto para sus aplicaciones Express.js, configuración de streamlining y configuración. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Utilice la herramienta generadora de aplicaciones, `express-generator`, para crear rápidamente un esqueleto de aplicación. + +Puede ejecutar el generador de aplicaciones con el comando `npx` (disponible en Node.js 8.2.0). + +```bash +$ generador de expresiones npx +``` + +Para versiones anteriores de Node, instale el generador de aplicaciones como un paquete global npm y luego ejecute: + +```bash +$ npm install -g express-generator +$ expreso +``` + +Mostrar las opciones de comando con la opción `-h`: + +```bash +$ express -h + + Uso: express [options] [dir] + + Opciones: + + -h, --help output output use information + --version output output the version number + -e, --ejs añadir soporte para motores ejs + --hbs añadir soporte para motores handlebars + --pug añadir soporte para pug engine + -H, --hogan añadir hogan. s engine soporta + --no-view generar sin el motor de vista + -v, --view add view support (ejs|hbs|hjs|jade|pug|twig|vash) (por defecto jade) + -c, --css add stylesheet support (less|Ninguno|brújula|sass) (por defecto a simple css) + --git add . itignore + -f, --force en directorio no vacío +``` + +Por ejemplo, lo siguiente crea una aplicación Express llamada *myapp*. La aplicación se creará en una carpeta llamada *myapp* en el directorio de trabajo actual y el motor de vistas se establecerá en Pug: + +```bash +$ express --view=pug myapp + + create : myapp + create : myapp/package.json + create : myapp/app. s + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index. s + crear : miapp/rutas/usuarios. s + create : myapp/public/stylesheets + create : myapp/public/stylesheets/style. ★ + create : myapp/views + create : myapp/views/index. ug + create : myapp/views/layout.pug + create : myapp/views/error. ug + create : myapp/bin + create : myapp/bin/www +``` + +Luego instale dependencias: + +```bash +$ cd myapp +$ npm install +``` + +En MacOS o Linux, ejecuta la aplicación con este comando: + +```bash +$ DEBUG=miapp:* npm inicio +``` + +En Windows Command Prompt, utilice este comando: + +```bash +> establecer DEBUG=miapp:* & npm start +``` + +En Windows PowerShell, utilice este comando: + +```bash +PS> $env:DEBUG='miapp:*'; npm start +``` + +Luego, carga `http://localhost:3000/` en tu navegador para acceder a la aplicación. + +La aplicación generada tiene la siguiente estructura de directorios: + +```bash +. +├── app.js +├── bin +│ └── www +├── package.json +├── public +│ ├── images +│ ├── javascripts +│ └── stylesheets +│ └── style.css +├── routes +│ ├── index.js +│ └── users.js +└── views + ├── error.pug + ├── index.pug + └── layout.pug + +7 directories, 9 files +``` + + + +La estructura de aplicaciones creada por el generador es sólo una de las muchas formas de estructurar aplicaciones Express. +Siéntase libre de usar esta estructura o modificarla para que se adapte mejor a sus necesidades. + + diff --git a/src/content/docs/es/5x/starter/hello-world.mdx b/src/content/docs/es/5x/starter/hello-world.mdx new file mode 100644 index 0000000000..7a005e4fa7 --- /dev/null +++ b/src/content/docs/es/5x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Hola ejemplo de mundo +description: Comienza con Express.js construyendo una sencilla aplicación 'Hola Mundo', demostrando la configuración básica y la creación de servidores para principiantes. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Incrustado a continuación es esencialmente la aplicación Express más simple que puede crear. Es una aplicación de archivo única +— *no* lo que obtendrías si utilizas el [generador Express](/en/starter/generator), que +crea el andamio para una aplicación completa con numerosos archivos JavaScript, plantillas de Jade y subdirectorios +para varios propósitos. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res. end('¡Hola Mundo!'); +}); + +app.listen(port, () => { + console.log(`Ejemplo de aplicación escuchando en el puerto ${port}`); +}); +``` + +Esta aplicación inicia un servidor y escucha en el puerto 3000 para las conexiones. La aplicación responde con "¡Hola Mundo!" para las solicitudes +a la URL raíz (`/`) o *route*. Por cada otro camino, responderá con un **404 No Encontrado**. + +## Ejecutar localmente + +Primero cree un directorio llamado `myapp`, cámbielo y ejecute `npm init`. Luego, instala `express` como una dependencia, según la [guía de instalación](/en/starter/installing). + +En el directorio `myapp`, crea un archivo llamado `app.js` y copia el código del ejemplo anterior. + + + +El `req` (petición) y `res` (respuesta) son los mismos objetos exactos que el Node proporciona, así que puedes +invocar `req. ipe()`, `req.on('data', callback)`, y cualquier otra cosa que hagas sin Express +involucradas. + + + +Ejecutar la aplicación con el siguiente comando: + +```bash +$ node app.js +``` + +Luego, carga `http://localhost:3000/` en un navegador para ver la salida. diff --git a/src/content/docs/es/5x/starter/installing.mdx b/src/content/docs/es/5x/starter/installing.mdx new file mode 100644 index 0000000000..25bf668243 --- /dev/null +++ b/src/content/docs/es/5x/starter/installing.mdx @@ -0,0 +1,41 @@ +--- +title: Instalando +description: Aprenda cómo instalar Express.js en su entorno Node.js, incluyendo la configuración del directorio de su proyecto y la gestión de dependencias con npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Antes de comenzar, asegúrese de que tiene instalado [Node.js](https://nodejs.org/) 18 o superior. Luego, crea un directorio para tu aplicación y navega por ella. + +```bash +mkdir myapp +cd myapp +``` + +Usa el comando `npm init` para crear un archivo `package.json` para tu aplicación. +Para más información sobre el funcionamiento de `package.json`, consulta [Especificaciones del manejo de package.json de npm](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +Este comando te pide varias cosas, como el nombre y la versión de tu aplicación. +Por ahora, puede simplemente pulsar RETURN para aceptar los valores predeterminados para la mayoría de ellos, con la siguiente excepción: + +``` +punto de entrada: (index.js) +``` + +Introduzca `app.js`, o lo que quiera que sea el nombre del archivo principal. Si desea que sea `index.js`, pulse RETURN para aceptar el nombre de archivo predeterminado sugerido. + +Ahora, instale Express en el directorio `myapp` y guárdelo en la lista de dependencias. Por ejemplo: + +```bash +npm instalar Express +``` + +Para instalar Express temporalmente y no añadirlo a la lista de dependencias: + +```bash +npm install express --no-save +``` diff --git a/src/content/docs/es/5x/starter/static-files.mdx b/src/content/docs/es/5x/starter/static-files.mdx new file mode 100644 index 0000000000..a614730632 --- /dev/null +++ b/src/content/docs/es/5x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Comprobando archivos estáticos en Express +description: Describa cómo servir archivos estáticos como imágenes, CSS y JavaScript en aplicaciones Express.js usando el middleware 'static' incorporado. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Para servir archivos estáticos como imágenes, archivos CSS, y archivos JavaScript, utiliza la función middleware integrada `express.static` en Express. + +La firma de la función es: + +```js +express.static(root, [options]); +``` + +El argumento `root` especifica el directorio raíz desde el cual servir activos estáticos. +Para más información sobre el argumento `options`, vea [express.static](/en/5x/api#express.static). + +Por ejemplo, utiliza el siguiente código para servir imágenes, archivos CSS y archivos JavaScript en un directorio llamado `public`: + +```js +app.use(express.static('public')); +``` + +Ahora, puedes cargar los archivos que están en el directorio `public`: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express busca los archivos relativos al directorio estático, por lo que el nombre del directorio estático +no es parte de la URL. + + + +Para usar múltiples directorios de activos estáticos, llama a la función middleware `express.static` varias veces: + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express busca los archivos en el orden en el que estableces los directorios estáticos con la función de middleware `express.static`. + + + +Para obtener mejores resultados, usa un proxy +inverso caché para mejorar el rendimiento de +sirviendo activos estáticos. + + + +Para crear un prefijo de ruta virtual (donde la ruta no existe en el sistema de archivos) para archivos que son servidos por el `express. función tatic`, [especificar una ruta de montaje](/en/5x/api#app.use) para el directorio estático, como se muestra a continuación: + +```js +app.use('/static', express.static('public')); +``` + +Ahora, puedes cargar los archivos que están en el directorio `public` desde el prefijo de ruta `/static`. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +Sin embargo, la ruta que proporcionas a la función `express.static` es relativa al directorio desde el cual inicias tu proceso `node`. Si ejecuta la aplicación expresa desde otro directorio, es más seguro utilizar la ruta absoluta del directorio que desea servir: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public'))); +``` + +Para más detalles sobre la función `serve-static` y sus opciones, vea [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/fr/4x/advanced/developing-template-engines.md b/src/content/docs/fr/4x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..8ddb890522 --- /dev/null +++ b/src/content/docs/fr/4x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Développement de moteurs de gabarits pour Express +description: Apprenez comment développer des moteurs de gabarits personnalisés pour Express.js en utilisant app.engine(), avec des exemples sur la création et l'intégration de votre propre logique de rendu de gabarits. +--- + +Utilisez la méthode `app.engine(ext, callback)` pour créer votre propre moteur de template. `ext` fait référence à l'extension de fichier, et `callback` est la fonction du moteur de gabarit, qui accepte les éléments suivants comme paramètres: l'emplacement du fichier, l'objet d'options et la fonction de rappel. + +Le code suivant est un exemple d'implémenter un moteur de gabarit très simple pour le rendu des fichiers `.ntl`. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +Votre application sera maintenant en mesure d'afficher les fichiers `.ntl`. Créez un fichier nommé `index.ntl` dans le dossier `views` avec le contenu suivant. + +```pug +#title# +#message# +``` + +Ensuite, créez la route suivante dans votre application. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +Lorsque vous faites une requête sur la page d'accueil, `index.ntl` sera rendu en HTML. diff --git a/src/content/docs/fr/4x/guide/behind-proxies.mdx b/src/content/docs/fr/4x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..1eabee667b --- /dev/null +++ b/src/content/docs/fr/4x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Exprimez derrière les mandataires +description: Apprenez à configurer les applications Express.js pour qu'elles fonctionnent correctement derrière les mandataires inversés, y compris en utilisant le paramètre proxy de confiance pour gérer les adresses IP du client. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Lorsque vous exécutez une application Express derrière un proxy inverse, certaines des API Express peuvent retourner des valeurs différentes de celles attendues. Pour ajuster pour cela, le paramètre `trust proxy` de l'application peut être utilisé pour exposer des informations fournies par le proxy inverse dans les API Express. Le problème le plus courant est les API express qui exposent l'adresse IP du client peut à la place afficher une adresse IP interne du proxy inverse. + + + +Lors de la configuration du paramètre `trust proxy`, il est important de comprendre la configuration exacte du proxy inverse +. Puisque ce paramètre fera confiance aux valeurs fournies dans la requête, Il est important que +la combinaison du paramètre dans Express corresponde à la façon dont le proxy inversé fonctionne. + + + +Le paramètre de l'application `trust proxy` peut être défini à l'une des valeurs listées dans la table suivante. + + + + + + + + + + + + + + + + + + + + + +
TypeValeur
Boolean +Si `true`, l'adresse IP du client est comprise comme l'entrée la plus à gauche dans l'en-tête `X-Forwarded-For`. + +Si `false`, l'application est comprise comme faisant directement face au client et l'adresse IP du client est dérivée de `req.socket.remoteAddress`. Ceci est le paramètre par défaut. + + +Lorsque vous définissez sur `true`, il est important de s'assurer que le dernier proxy inversé fiable est de supprimer/écraser tous les en-têtes HTTP suivants : `X-Forwarded-For`, `X-Forwarded-Host`, et `X-Forwarded-Proto`, sinon il sera possible pour le client de fournir n'importe quelle valeur. + +
Adresses IP +Une adresse IP, un sous-réseau ou un tableau d'adresses IP et de sous-réseaux à confier comme étant un proxy inverse. La liste suivante montre les noms de sous-réseaux pré-configurés : + +* loopback - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +Vous pouvez définir les adresses IP de l'une des façons suivantes : + +```js +app.set('trust proxy', 'loopback'); // specify a single subnet +app.set('trust proxy', 'loopback, 123.123.123.123'); // specify a subnet and an address +app.set('trust proxy', 'loopback, linklocal, uniquelocal'); // specify multiple subnets as CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // specify multiple subnets as an array +``` + +Lorsqu'il est spécifié, les adresses IP ou les sous-réseaux sont exclus du processus de détermination de l'adresse, et l'adresse IP non fiable la plus proche du serveur d'application est déterminée comme l'adresse IP du client. Cela fonctionne en vérifiant si `req.socket.remoteAddress` est fiable. Si c'est le cas, alors chaque adresse dans `X-Forwarded-For` est vérifiée de droite à gauche jusqu'à la première adresse non fiable. + +
Nombre +Utilisez l'adresse qui est au plus `n` nombre de sauts loin de l'application Express. `req.socket.remoteAddress` est le premier saut, et le reste est recherché dans l'en-tête `X-Forwarded-For` de droite à gauche. Une valeur de `0` signifie que la première adresse non fiable serait `req.socket.remoteAddress`, c'est-à-dire qu'il n'y a pas de proxy inverse. + + +Lors de l'utilisation de ce paramètre, il est important de s'assurer qu'il n'y a pas de multiples, chemins différents vers l'application Express de sorte que le client peut être inférieur au nombre de sauts configurés, sinon il pourrait être possible pour le client de fournir n'importe quelle valeur. + +
Fonction +Implémentation de confiance personnalisée. + +```js +app.set('trust proxy', (ip) => { + if (ip === '127.0.0.1' || ip === '123.123.123. 23') + retourne true; // les adresses IP + approuvées retournent false; +}); +``` + +
+ +Activer `trust proxy` aura l'impact suivant : + +
    +
  • + La valeur de [req.hostname](/en/api#req.hostname) est dérivée de la valeur définie dans l'en-tête + `X-Forwarded-Host`, qui peut être définie par le client ou par le proxy. +
    • +
  • + `X-Forwarded-Proto` peut être défini par le proxy inverse pour dire à l'application si c'est `https` ou + `http` ou même un nom invalide. Cette valeur est reflétée par [req.protocol](/en/api#req.protocol). +
    • +
  • + Les valeurs [req.ip](/en/api#req.ip) et [req.ips](/en/api#req.ips) sont remplies en fonction de l'adresse du socket + et de l'en-tête `X-Forwarded-For`, à partir de la première adresse non fiable. +
    • +
+ +Le paramètre `trust proxy` est implémenté en utilisant le paquet [proxy-addr](https://www.npmjs.com/package/proxy-addr). Pour plus d'informations, voir sa documentation. diff --git a/src/content/docs/fr/4x/guide/debugging.mdx b/src/content/docs/fr/4x/guide/debugging.mdx new file mode 100644 index 0000000000..04a54bbf25 --- /dev/null +++ b/src/content/docs/fr/4x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Débogage Express +description: Apprenez comment activer et utiliser les journaux de débogage dans les applications Express.js en définissant la variable d'environnement DEBUG pour un dépannage amélioré. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Pour voir tous les journaux internes utilisés dans Express, définissez la variable d'environnement `DEBUG` à +`express:*` lors du lancement de votre application. + +```bash +$ DEBUG=express:* node index.js +``` + +Sous Windows, utilisez la commande correspondante. + +```bash +> $env:DEBUG = "express:*"; node index.js +``` + +L'exécution de cette commande sur l'application par défaut générée par le [générateur express](/en/starter/generator) affiche la sortie suivante: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +Lorsqu'une demande est faite à l'application, vous verrez les journaux spécifiés dans le code Express: + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index. ug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +Pour voir les logs uniquement à partir de l'implémentation du routeur, définissez la valeur de `DEBUG` à `express:router`. De même, pour ne voir que les logs de l'implémentation de l'application, définissez la valeur de `DEBUG` à `express:application`, et ainsi de suite. + +## Applications générées par `express` + +Une application générée par la commande `express` utilise le module `debug` et son espace de noms de débogage est limité au nom de l'application. + +Par exemple, si vous avez généré l'application avec `$ express sample-app`, vous pouvez activer les instructions de débogage avec la commande suivante : + +```bash +$ DEBUG=sample-app:* node ./bin/www +``` + +Vous pouvez spécifier plus d'un espace de noms de débogage en assignant une liste de noms séparés par des virgules : + +```bash +$ DEBUG=http,mail,express:* node index.js +``` + +## Options avancées + +Lors de l'exécution de Node.js, vous pouvez définir quelques variables d'environnement qui changeront le comportement du journal de débogage : + +| Nom | Objectif | +| ------------------- | ---------------------------------------------------------------- | +| `DEBUG` | Active/désactive les espaces de noms de débogage spécifiques. | +| `DEBUG_COLORS` | Utiliser ou non les couleurs dans la sortie de débogage. | +| `DEBUG_DEPTH` | Profondeur de l'inspection des objets. | +| `DEBUG_FD` | Descripteur de fichier vers lequel écrire la sortie de débogage. | +| `DEBUG_SHOW_HIDDEN` | Affiche les propriétés masquées sur les objets inspectés. | + + + +Les variables d'environnement commençant par `DEBUG_` finissent par être converties en un objet d'options +qui est utilisé avec les formats `%o`/`%O`. Voir la documentation Node.js pour +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) pour la liste complète +. + + diff --git a/src/content/docs/fr/4x/guide/error-handling.mdx b/src/content/docs/fr/4x/guide/error-handling.mdx new file mode 100644 index 0000000000..1ef9f11421 --- /dev/null +++ b/src/content/docs/fr/4x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Gestion des erreurs +description: Comprenez comment Express.js gère les erreurs dans le code synchrone et asynchrone et apprend à implémenter la gestion des erreurs personnalisées pour vos applications. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Error Handling* fait référence à la façon dont Express attrape et traite les erreurs que +se produisent de manière synchronisée et asynchrone. Express comes with a default error +handler so you don't need to write your own to get started. + +## Erreurs de capture + +Il est important de s'assurer qu'Express attrape toutes les erreurs qui se produisent lorsque +exécute des gestionnaires de routes et des middleware. + +Les erreurs qui se produisent dans le code synchrone dans les gestionnaires de route et les middleware +ne nécessitent aucun travail supplémentaire. If synchronous code throws an error, then Express will +catch and process it. Par exemple : + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Express va attraper cela tout seul. +}); +``` + +For errors returned from asynchronous functions invoked by route handlers +and middleware, you must pass them to the `next()` function, where Express will +catch and process them. Par exemple : + +```js +app.get('/', (req, res, next) => { + fs. eadFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Passez des erreurs à Express. + } else { + res. end(data); + } + }); +}); +``` + +À partir de Express 5, les gestionnaires de route et les middleware qui retournent une Promise +appelleront automatiquement `next(value)` quand ils rejettent ou lancent une erreur. +Par exemple : + +```js +app.get('/user/:id', async (req, res, next) => { + const user = wait getUserById(req.params.id); + res.send(user); +}); +``` + +Si `getUserById` lance une erreur ou un rejet, `next` sera appelé avec soit +l'erreur émise ou la valeur rejetée. Si aucune valeur rejetée n'est fournie, `next` +sera appelée avec un objet Error par défaut fourni par le routeur Express. + +If you pass anything to the `next()` function (except the string `'route'`), +Express regards the current request as being an error and will skip any +remaining non-error handling routing and middleware functions. + +Si le callback dans une séquence ne fournit aucune donnée, seulement des erreurs, vous pouvez simplifier +ce code comme suit: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +Dans l'exemple ci-dessus, `next` est fourni comme callback pour `fs.writeFile`, +qui est appelé avec ou sans erreurs. S'il n'y a pas d'erreur, le second +est exécuté, sinon Express attrape et traite l'erreur. + +Vous devez attraper les erreurs qui se produisent dans le code asynchrone invoqué par les gestionnaires de route ou +middleware et les passer à Express pour le traitement. Par exemple : + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + essayez { + throw new Error('BROKEN'); + } attraper (err) { + next(err); + } + }, 100); +}); +``` + +L'exemple ci-dessus utilise un bloc `try...catch` pour attraper des erreurs dans le code +asynchrone et les passer à Express. Si le bloc `try...catch` +était omis, Express ne attrapera pas l'erreur car il ne fait pas partie du code du gestionnaire +synchrone. + +Utilise des promesses pour éviter les frais généraux du bloc `essayer...catch` ou lorsque tu utilises les fonctions +qui renvoient des promesses. Par exemple : + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + . hen(() => { + throw new Error('BROKEN'); + }) + . atch(next); // Les erreurs seront passées à Express. +}); +``` + +Puisque les promesses attrapent automatiquement à la fois les erreurs synchrones et les promesses rejetées, +vous pouvez simplement fournir `next` car le gestionnaire de capture final et Express attrapera des erreurs, +parce que le gestionnaire de capture est donné l'erreur comme premier argument. + +Vous pouvez également utiliser une chaîne de gestionnaires pour vous fier à l'erreur synchrone +attrapant, en réduisant le code asynchrone à quelque chose de trivial. Par exemple : + +```js +app.get('/', [ + function (req, res, next) { + fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals. ata = data; + next(err); + }); + }, + fonction (req, res) { + res. ocals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +L'exemple ci-dessus a quelques déclarations triviales de l'appel `readFile` +. Si `readFile` cause une erreur, alors il passe l'erreur à Express, sinon vous +revenez rapidement au monde de la gestion des erreurs synchrones dans le prochain gestionnaire +de la chaîne. Ensuite, l'exemple ci-dessus tente de traiter les données. Si cela échoue, alors le gestionnaire d'erreurs synchrone +l'attrapera. Si vous aviez fait ce traitement à l'intérieur de +la callback `readFile`, alors l'application pourrait quitter et les gestionnaires d'erreur +Express ne s'exécuteraient pas. + +Quelle que soit la méthode que vous utilisez, si vous voulez que les gestionnaires d'erreur Express soient appelés et que l'application +survive, vous devez vous assurer qu'Express reçoit l'erreur. + +## Le gestionnaire d'erreur par défaut + +Express est livré avec un gestionnaire d'erreur intégré qui prend en charge toutes les erreurs qui peuvent être rencontrées dans l'application. Cette fonction middleware par défaut est ajoutée à la fin de la pile de fonctions du middleware. + +Si vous passez une erreur à `next()` et que vous ne la gérez pas dans un gestionnaire d'erreur personnalisé +, il sera géré par le gestionnaire d'erreur intégré ; l'erreur sera +écrite au client avec la trace de la pile. La trace de la pile n'est pas incluse +dans l'environnement de production. + + + +Définissez la variable d'environnement `NODE_ENV` à `production`, pour exécuter l'application en mode production. + + + +Lorsqu'une erreur est écrite, les informations suivantes sont ajoutées à la réponse +: + +* Le `res.statusCode` est défini à partir de `err.status` (ou `err.statusCode`). Si + cette valeur est en dehors de la plage 4xx ou 5xx, elle sera définie à 500. +* Le `res.statusMessage` est défini selon le code de statut. +* Le corps sera le HTML du message de code de statut lorsque l'environnement de production + , sinon sera `err.stack`. +* N'importe quel en-tête spécifié dans un objet `err.headers`. + +Si vous appelez `next()` avec une erreur après avoir commencé à écrire la réponse +(par exemple, si vous rencontrez une erreur lors du streaming de la réponse +au client), le gestionnaire d'erreur par défaut Express ferme la connexion +et échoue la requête. + +Ainsi, lorsque vous ajoutez un gestionnaire d'erreurs personnalisé, vous devez déléguer à +le gestionnaire d'erreur Express par défaut, lorsque les en-têtes +ont déjà été envoyés au client : + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Notez que le gestionnaire d'erreur par défaut peut être déclenché si vous appelez `next()` avec une erreur +dans votre code plusieurs fois, même si une gestion personnalisée des erreurs est en place. + +D'autres erreurs de gestion du middleware peuvent être trouvées dans [middleware Express](/en/resources/middleware). + +## Écriture des gestionnaires d'erreurs + +Définissez les fonctions du middleware de la même manière que les autres fonctions du middleware, +excepté les fonctions de gestion des erreurs ont quatre arguments au lieu de trois: +`(err, req, res, next)`. Par exemple : + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Quelque chose s'est cassé !'); +}); +``` + +Vous définissez le middleware en dernier lieu, après d'autres appels `app.use()` et routage des appels; par exemple: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser. rlencoded({ + étendu: true, + }) +); +app.use(bodyParser.json()); +app. se(methodOverride()); +app.use((err, req, res, next) => { + // logique +}); +``` + +Les réponses provenant d'une fonction middleware peuvent être dans n'importe quel format, comme une page d'erreur HTML, un message simple ou une chaîne JSON. + +Pour des raisons organisationnelles (et pour un cadre de plus haut niveau), vous pouvez définir +plusieurs fonctions de gestion des erreurs du middleware, tout comme vous le feriez avec les fonctions +régulières du middleware. Par exemple, pour définir un gestionnaire d'erreurs +pour les requêtes faites en utilisant `XHR` et ceux sans : + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +application. se( + bodyParser.urlencoded({ + étendu: true, + }) +); +app. se(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +Dans cet exemple, les génériques `logErrors` peuvent écrire la requête et les informations d'erreur +à `stderr`, par exemple : + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +Aussi dans cet exemple, `clientErrorHandler` est défini comme suit ; dans ce cas, l'erreur est explicitement passée au suivant. + +Notez que lorsque *not* appelez "next" dans une fonction de gestion des erreurs, vous êtes responsable de l'écriture (et de la fin) de la réponse. Sinon, ces demandes seront « bloquées » et ne seront pas admissibles au ramassage des déchets. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500). end({ error: 'Quelque chose a échoué!' }); + } else { + next(err); + } +} +``` + +Implémenter la fonction "catch-all" `errorHandler` comme suit (par exemple): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +Si vous avez un gestionnaire de route avec plusieurs fonctions de rappel, vous pouvez utiliser le paramètre `route` pour passer au gestionnaire de route suivant. Par exemple : + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user. asPaid) { + // continue à gérer cette requête + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent. ind(err, doc) => { + if (err) return next(err); + res. son(doc); + }); + } +); +``` + +Dans cet exemple, le gestionnaire `getPaidContent` sera ignoré, mais tous les gestionnaires restants dans `app` pour `/a_route_behind_paywall` continueront d'être exécutés. + + + +Les appels à `next()` et `next(err)` indiquent que le gestionnaire actuel est complet et dans quel état. +`next(err)` sautera tous les gestionnaires restants de la chaîne, à l'exception de ceux qui sont configurés à +gérer les erreurs comme décrit ci-dessus. + + diff --git a/src/content/docs/fr/4x/guide/overriding-express-api.md b/src/content/docs/fr/4x/guide/overriding-express-api.md new file mode 100644 index 0000000000..fdd81c674a --- /dev/null +++ b/src/content/docs/fr/4x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Outrepasser l'API Express +description: Découvrez comment personnaliser et étendre l'API Express.js en écrasant les méthodes et les propriétés sur les objets de demande et de réponse à l'aide de prototypes. +--- + +L'API Express se compose de différentes méthodes et propriétés sur les objets de requête et de réponse. Celles-ci sont héritées du prototype. Il y a deux points d'extension pour l'API Express : + +1. Les prototypes globaux à `express.request` et `express.response`. +2. Prototypes spécifiques à l'application à `app.request` et `app.response`. + +Modifier les prototypes globaux affectera toutes les applications Express chargées dans le même processus. Si vous le souhaitez, les modifications peuvent être apportées à l'application en modifiant uniquement les prototypes spécifiques à l'application après avoir créé une nouvelle application. + +## Méthodes + +Vous pouvez remplacer la signature et le comportement des méthodes existantes avec vos propres méthodes en assignant une fonction personnalisée. + +Voici un exemple de surcharge du comportement de [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +L'implémentation ci-dessus modifie complètement la signature originale de `res.sendStatus`. Il accepte maintenant un code de statut, un type d'encodage, et le message à envoyer au client. + +La méthode surchargée peut maintenant être utilisée de cette manière: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## Propriétés + +Les propriétés de l'API Express sont soit : + +1. Propriétés assignées (ex: `req.baseUrl`, `req.originalUrl`) +2. Défini comme getters (ex: `req.secure`, `req.ip`) + +Puisque les propriétés de la catégorie 1 sont assignées dynamiquement sur les objets `request` et `response` dans le contexte du cycle de réponse de la requête courante, leur comportement ne peut pas être remplacé. + +Les propriétés de la catégorie 2 peuvent être écrasées en utilisant l'API des extensions API Express. + +Le code suivant réécrit comment la valeur de `req.ip` doit être dérivée. Maintenant, il retourne simplement la valeur de l'en-tête de la requête `Client-IP`. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Prototype + +Afin de fournir l'API Express, les objets de requête/réponse passés à Express (via `app(req, res)`, par exemple) doivent hériter de la même chaîne de prototypes. Par défaut, c'est `http.IncomingRequest.prototype` pour la requête et `http.ServerResponse.prototype` pour la réponse. + +Sauf si nécessaire, il est recommandé de le faire uniquement au niveau de l'application, plutôt qu'au niveau mondial. Veillez également à ce que le prototype utilisé corresponde le plus près possible à la fonctionnalité des prototypes par défaut. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/fr/4x/guide/routing.mdx b/src/content/docs/fr/4x/guide/routing.mdx new file mode 100644 index 0000000000..65e3d690e4 --- /dev/null +++ b/src/content/docs/fr/4x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Routage +description: Apprenez à définir et utiliser des routes dans les applications Express.js, y compris les méthodes de trajet, les chemins de trajet, les paramètres et l'utilisation du routeur pour le routage modulaire. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* indique comment les terminaux (URIs) d'une application répondent aux requêtes du client. +Pour une introduction au routage, voir [Routage de base](/en/starter/basic-routing). + +Vous définissez le routage à l'aide des méthodes de l'objet Express `app` qui correspondent aux méthodes HTTP; +par exemple, `app. et()` pour gérer les requêtes GET et `app.post` pour gérer les requêtes POST. Pour une liste complète, +voir [app.METHOD](/en/5x/api#app.METHOD). Vous pouvez également utiliser [app.all()](/en/5x/api#app.all) pour gérer toutes les méthodes HTTP et [app. se()](/en/5x/api#app.use) à +spécifient le middleware comme fonction de callback (Voir [Utilisation du middleware](/en/guide/using-middleware) pour plus de détails). + +Ces méthodes de routage spécifient une fonction de rappel (parfois appelée "fonctions de gestionnaire") appelée lorsque l'application reçoit une requête vers la route spécifiée (endpoint) et la méthode HTTP. En d'autres termes, l'application "écoute" les requêtes qui correspondent à la(les) route(s) spécifiée(s) et à la(les) méthode(s), et quand il détecte une correspondance, il appelle la fonction de rappel spécifiée. + +En fait, les méthodes de routage peuvent avoir plus d'une fonction de rappel en tant qu'arguments. +Avec plusieurs fonctions de rappel, il est important de fournir `next` comme argument à la fonction de callback puis appeler `next()` dans le corps de la fonction pour distribuer le contrôle +au prochain rappel. + +Le code suivant est un exemple de route très basique. + +```js +const express = require('express'); +const app = express(); + +// répond avec "bonjour le monde" lorsqu'une demande GET est faite à l'application +de la page d'accueil. et('/', (req, res) => { + res.send('bonjour le monde'); +}); +``` + +## Méthodes de la route + +Une méthode de route est dérivée d'une des méthodes HTTP, et est attachée à une instance de la classe `express`. + +Le code suivant est un exemple de routes qui sont définies pour le `GET` et les méthodes `POST` à la racine de l'application. + +```js +// Route de la méthode GET +app.get('/', (req, res) => { + res. end('Requête GET sur la page d'accueil'); +}); + +// La méthode POST route +app. ost('/', (req, res) => { + res.send('Requête POST sur la page d'accueil'); +}); +``` + +Express supporte les méthodes qui correspondent à toutes les méthodes de requête HTTP : `get`, `post`, et ainsi de suite. +Pour une liste complète, voir [app.METHOD](/en/5x/api#app.METHOD). + +Il y a une méthode de routage spéciale, `app.all()`, utilisée pour charger les fonctions du middleware à un chemin pour *toutes* les méthodes de requête HTTP. Par exemple, le gestionnaire suivant est exécuté pour les requêtes vers la route `"/secret"` si vous utilisez `GET`, `POST`, `PUT`, `DELETE`, ou toute autre méthode de requête HTTP supportée dans le module [http](https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Accéder à la section secrète ...'); + next(); // passer le contrôle au prochain gestionnaire +}); +``` + +## Chemins de la route + +Les chemins de la route, en combinaison avec une méthode de requête, définissent les points de terminaison à partir desquels les requêtes peuvent être faites. Les chemins de route peuvent être des chaînes, des chaînes de caractères ou des expressions régulières. + + + +En express 5, les caractères `? , `+`, `\*`, `[]`et `()\` sont gérés différemment de la version +4, veuillez consulter le [guide de migration](/en/guide/migrating-5#path-syntax) pour plus d'informations. + + + + + +Dans l'expression expresse 4, des caractères d'expression régulière tels que `$` doivent être échappés avec un `\`. + + + + + +Express utilise [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) pour correspondre aux chemins de la route +; consultez la documentation path-to-regexp pour toutes les possibilités dans la définition des chemins d'itinéraire. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) est un outil pratique pour +qui teste les routes Express de base, bien qu'il ne supporte pas la recherche de masques. + + + +Les chaînes de requête ne font pas partie du chemin de la route. + +### Chemins de route basés sur des chaînes de caractères + +Ce chemin de route correspond aux requêtes vers la route racine, `/`. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +Ce chemin de route correspond aux requêtes à `/about`. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +Ce chemin de route correspondra aux requêtes à `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Chemins de route basés sur des chaînes de caractères + + + +Les masques de chaînes de caractères dans Express 5 ne fonctionnent plus. Veuillez vous référer au guide de migration + pour plus d'informations. + + + +Ce chemin de route correspondra à `acd` et `abcd`. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +Ce chemin correspondra à `abcd`, `abbcd`, `abbbcd`, et ainsi de suite. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +Ce chemin correspondra à `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd`, et ainsi de suite. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +Ce chemin de route correspondra à `/abe` et `/abcde`. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Chemins de route basés sur des expressions régulières + +Ce chemin d'itinéraire correspondra à tout ce qui contient un "a". + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +Ce chemin d'itinéraire correspondra à `butterfly` et `dragonfly`, mais pas `butterflyman`, `dragonflyman`, et ainsi de suite. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Paramètres de la route + +Les paramètres de la route sont des segments d'URL nommés qui sont utilisés pour capturer les valeurs spécifiées à leur position dans l'URL. Les valeurs capturées sont remplies dans l'objet `req.params`, avec le nom du paramètre route spécifié dans le chemin comme leurs clés respectives. + +``` +Chemin de la route : /users/:userId/books/:bookId +URL de requête : http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +Pour définir des routes avec des paramètres d'itinéraire, il suffit de spécifier les paramètres de l'itinéraire dans le chemin de la route comme indiqué ci-dessous. + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +Le nom des paramètres de route doit être composé de "mots caractères" ([A-Za-z0-9_]). + + + +Puisque le trait d'union (`-`) et le point (`.`) sont interprétés littéralement, ils peuvent être utilisés avec des paramètres d'itinéraire à des fins utiles. + +``` +Chemin de la route : /flights/:from-:to +URL de requête : http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Chemin de la route : /plantae/:genus.:espèce +URL de requête : http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +Dans l’express 5, les caractères Regexp ne sont pas pris en charge dans les chemins de route, pour plus d’informations, veuillez +vous référer au [guide de migration](/en/guide/migrating-5#path-syntax). + + + +Pour avoir plus de contrôle sur la chaîne exacte qui peut être associée à un paramètre de route, vous pouvez ajouter une expression régulière entre parenthèses (`()`) : + +``` +Chemin de la route : /user/:userId(\d+) +URL de requête : http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Parce que l'expression régulière fait généralement partie d'une chaîne littérale, Assurez-vous d'échapper à n'importe quel caractère `\` +avec un antislash supplémentaire, par exemple `\d+`. + + + + +Dans Express 4.x, le caractère `*` dans les expressions régulières n'est pas interprété de la manière habituelle. Comme solution de contournement, utilisez `{0,}` au lieu de `*`. Cela sera probablement corrigé dans Express 5. + + +## Gestionnaires de routes + +Vous pouvez fournir plusieurs fonctions de rappel qui se comportent comme [middleware](/en/guide/using-middleware) pour traiter une requête. La seule exception est que ces callbacks peuvent appeler `next('route')` pour contourner les rappels de route restants. Vous pouvez utiliser ce mécanisme pour imposer des conditions préalables sur une route, passent ensuite le contrôle aux routes suivantes s'il n'y a pas de raison de poursuivre l'itinéraire courant. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params. d === '0') { + return next('route'); + } + res. end(`Utilisateur ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Gestionnaire spécial pour l'identifiant utilisateur 0'); +}); +``` + +Dans cet exemple : + +* `GET /user/5` → géré par la première route → envoie "Utilisateur 5" +* `GET /user/0` → première route appelle `next('route')`, passe à la prochaine route correspondant à `/user/:id` + +Les gestionnaires de routes peuvent être sous la forme d'une fonction, d'un tableau de fonctions, ou de combinaisons des deux, comme indiqué dans les exemples suivants. + +Une seule fonction de rappel peut gérer une route. Par exemple : + +```js +app.get('/example/a', (req, res) => { + res.send('Bonjour de A!'); +}); +``` + +Plus d'une fonction de rappel peut gérer une route (assurez-vous de spécifier l'objet `next`). Par exemple : + +```js +app.get( + '/example/b', + (req, res, next) => { + console. og('la réponse sera envoyée par la fonction suivante . .'); + next(); + }, + (req, res) => { + end('Bonjour de B!'); + } +); +``` + +Un tableau de fonctions de rappel peut gérer une route. Par exemple : + +```js +const cb0 = function (req, res, suivant) { + console. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +const cb2 = function (req, res) { + end('Bonjour de C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +Une combinaison de fonctions indépendantes et de tableaux de fonctions peut gérer une route. Par exemple : + +```js +const cb0 = function (req, res, suivant) { + console. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + suivante(); +}; + +app. et( + '/example/d', + [cb0, cb1], + (req, res, next) => { + console. og('la réponse sera envoyée par la fonction suivante . .'); + next(); + }, + (req, res) => { + res. end('Bonjour de D!'); + } +); +``` + +## Méthodes de réponse + +Les méthodes de l'objet de réponse (`res`) dans la table suivante peuvent envoyer une réponse au client et terminer le cycle de réponse de la requête. Si aucune de ces méthodes n'est appelée à partir d'un gestionnaire d'itinéraire, la requête du client sera suspendue. + +| Méthode | Libellé | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | Demander au téléchargement un fichier. | +| [res.end()](/en/5x/api#res.end) | Terminer le processus de réponse. | +| [res.json()](/en/5x/api#res.json) | Envoyer une réponse JSON. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Envoyer une réponse JSON avec le support JSONP. | +| [res.redirect()](/en/5x/api#res.redirect) | Rediriger une requête. | +| [res.render()](/en/5x/api#res.render) | Afficher un modèle de vue. | +| [res.send()](/en/5x/api#res.send) | Envoyer une réponse de différents types. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Envoyer un fichier en tant que flux octet. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Définit le code de statut de la réponse et envoie sa représentation en tant que corps de réponse. | + +## app.route() + +Vous pouvez créer des gestionnaires de routes chaînables pour un chemin en utilisant `app.route()`. +Parce que le chemin est spécifié à un seul endroit, la création de routes modulaires est utile, tout comme la réduction de la redondance et des fautes de frappe. Pour plus d'informations sur les routes, voir : [Documentation de Router()](/en/5x/api#router). + +Voici un exemple de gestionnaires de routes enchaînés qui sont définis en utilisant `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + end('Obtenir un livre aléatoire'); + }) + . ost((req, res) => { + res.send('Ajouter un livre'); + }) + . ut((req, res) => { + res.send('Mettre à jour le livre'); +}); +``` + +## Routeur + +Utilisez la classe `express.Router` pour créer des gestionnaires de route modulaires et montables. Une instance `Router` est un système complet de middleware et de routage ; pour cette raison, elle est souvent appelée "mini-app". + +L'exemple suivant crée un routeur en tant que module, charge une fonction middleware dedans, définit quelques routes, et monte le module routeur sur un chemin dans l'application principale. + +Créez un fichier de routeur nommé `birds.js` dans le répertoire de l'application, avec le contenu suivant : + +```js +const express = require('express'); +const router = express.Router(); + +// middleware that is specific to this router +const timeLog = (req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}; +router.use(timeLog); + +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Ensuite, chargez le module routeur dans l'application : + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', oiseaux); +``` + +L'application sera maintenant en mesure de traiter les demandes vers `/birds` et `/birds/about`, ainsi que d'appeler la fonction middleware `timeLog` qui est spécifique à la route. + +Mais si la route parente `/birds` a des paramètres de chemin, elle ne sera pas accessible par défaut à partir des sous-routes. Pour le rendre accessible, vous devrez passer l'option `mergeParams` au constructeur de routeur [reference](/en/5x/api#app.use). + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/fr/4x/guide/using-middleware.mdx b/src/content/docs/fr/4x/guide/using-middleware.mdx new file mode 100644 index 0000000000..36277e0b0c --- /dev/null +++ b/src/content/docs/fr/4x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Utilisation du middleware +description: Apprenez à utiliser les middleware dans les applications Express.js, y compris les middleware de niveau application et routeur, la gestion des erreurs et l'intégration de logiciels tiers middleware. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express est un framework web de routage et de middleware qui possède des fonctionnalités minimales : Une application Express est essentiellement une série d'appels de fonctions de middleware. + +Les fonctions *Middleware* sont des fonctions qui ont accès à l'objet [request object](/en/5x/api#req) (`req`), l'objet [réponse](/en/5x/api#res) (`res`), et la prochaine fonction du middleware dans le cycle de réponse de l'application. La prochaine fonction du middleware est généralement dénotée par une variable nommée `next`. + +Les fonctions Middleware peuvent effectuer les tâches suivantes : + +* Exécuter n'importe quel code. +* Effectuez des modifications à la requête et aux objets de réponse. +* Termine le cycle de réponse de la requête. +* Appeler la prochaine fonction du middleware dans la pile. + +Si la fonction middleware actuelle ne met pas fin au cycle de réponse de requête, elle doit appeler `next()` pour passer le contrôle à la prochaine fonction du middleware. Sinon, la demande sera laissée en suspens. + +Une application Express peut utiliser les types de middleware suivants : + +* (#middleware.application) +* [middleware au niveau du routeur] (#middleware.router) +* (#middleware.error-handling) +* (#middleware.built-in) +* [middleware de tierce partie](#middleware.third-party) + +Vous pouvez charger le middleware au niveau de l'application et du routeur avec un chemin de montage optionnel. +Vous pouvez également charger une série de fonctions middleware ensemble, ce qui crée une sous-pile du système middleware à un point de montage. + +## Outil d'interface de l'application + +Lier le middleware au niveau de l'application à une instance de l'objet [app object](/en/5x/api#app) en utilisant `app.use()` et `app. Les fonctions ETHOD()`, où `METHOD` est la méthode HTTP de la requête que la fonction middleware gère (comme GET, PUT ou POST) en minuscule. + +Cet exemple montre une fonction middleware sans chemin de montage. La fonction est exécutée chaque fois que l'application reçoit une requête. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +Cet exemple montre une fonction middleware montée sur le chemin `/user/:id`. La fonction est exécutée pour n'importe quel type de requête HTTP +sur le chemin `/user/:id`. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +Cet exemple montre une route et sa fonction de gestion (système middleware). La fonction gère les requêtes GET vers le chemin `/user/:id`. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +Voici un exemple de chargement d'une série de fonctions middleware à un point de montage, avec un chemin de montage. +Il illustre une sous-pile middleware qui affiche les informations de requête pour tout type de requête HTTP vers le chemin `/user/:id`. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + console. og('Type de requête :', req.method); + suivant(); + } +; +``` + +Les gestionnaires de routes vous permettent de définir plusieurs routes pour un chemin. L'exemple ci-dessous définit deux routes pour les requêtes GET vers le chemin `/user/:id`. La deuxième route ne posera aucun problème, mais elle ne sera jamais appelée parce que le premier parcours termine le cycle de réponse de la requête. + +Cet exemple montre une sous-pile middleware qui gère les requêtes GET vers le chemin `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req. arams.id); + next(); + }, + (req, res, next) => { + res. end('Info utilisateur'); + } +); + +// gestionnaire pour le chemin /user/:id qui affiche l'identifiant utilisateur +. et('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +Pour sauter le reste des fonctions du middleware à partir d'une pile de middleware du routeur, appelez `next('route')` pour passer le contrôle à la route suivante. + + + +`next('route')` ne fonctionnera que dans les fonctions du middleware qui ont été chargées en utilisant les fonctions +`app.METHOD()` ou `router.METHOD()`. + + + +Cet exemple montre une sous-pile middleware qui gère les requêtes GET vers le chemin `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + // si l'identifiant de l'utilisateur est 0, passer à la route + suivante si (req. arams. d === '0') next('route'); + // sinon passez le contrôle à la prochaine fonction du middleware de cette pile + else next(); + }, + (req, res, next) => { + // envoie une réponse régulière + res. end('regular'); + } +); + +// gestionnaire pour le chemin /user/:id qui envoie une réponse spéciale +. et('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +Les Middleware peuvent également être déclarés dans un tableau pour être réutilisables. + +Cet exemple montre un tableau avec une sous-pile middleware qui gère les requêtes GET vers le chemin `/user/:id` + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req. riginalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Type de requête:', req. ethod); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app. et('/user/:id', logStuff, (req, res, next) => { + res.send('User Info'); +}); +``` + +## middleware au niveau du routeur + +Le middleware au niveau du routeur fonctionne de la même manière que le middleware au niveau de l'application, sauf qu'il est lié à une instance de `express.Router()`. + +```js +routeur const = express.Router(); +``` + +Charger le middleware au niveau du routeur en utilisant les fonctions `router.use()` et `router.METHOD()`. + +L'exemple suivant réplique le système middleware qui est affiché ci-dessus pour le middleware au niveau de l'application, en utilisant le middleware au niveau du routeur: + +```js +const express = require('express'); +const app = express(); +const router = express. і(); + +// une fonction middleware sans chemin de montage. Ce code est exécuté pour chaque requête au routeur +. se(req, res, next) => { + console.log('Heure:', Date. ow()); + next(); +}); + +// une sous-pile middleware affiche les informations de requête pour tout type de requête HTTP vers le routeur /user/:id path +. se( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + . og('Type de requête:', req. ethod); + suivante(); + } +); + +// une sous-pile middleware qui gère les requêtes GET sur le routeur /user/:id path +. et( + '/user/:id', + (req, res, next) => { + // si l'identifiant de l'utilisateur est 0, passer au routeur + suivant si (req. arams. d === '0') next('route'); + // passe autrement le contrôle à la prochaine fonction du middleware de cette pile + else next(); + }, + (req, res, next) => { + // renvoie une page normale + res. ender('regular'); + } +); + +// gestionnaire pour le chemin /user/:id qui affiche une page spéciale +. et('/user/:id', (req, res, next) => { + . og(req.params.id); + res.render('special'); +}); + +// monte le routeur sur l'application +app.use('/', router); +``` + +Pour sauter le reste des fonctions du middleware du routeur, appelez `next('router')` +pour passer le contrôle hors de l'instance du routeur. + +Cet exemple montre une sous-pile middleware qui gère les requêtes GET vers le chemin `/user/:id`. + +```js +const express = require('express'); +const app = express(); +const router = express. і(); + +// prédice le routeur avec un contrôle et un renflouement si nécessaire le routeur +. se(req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +routeur. et('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// utilise le routeur et 401 tout ce qui passe par l'application +. se('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## Gestion des erreurs du middleware + + + +La gestion d'erreurs du middleware prend toujours *four* arguments. Vous devez fournir quatre arguments à +l'identifier comme une fonction de gestion des erreurs du middleware. Même si vous n'avez pas besoin d'utiliser l'objet `next` +, vous devez le spécifier pour maintenir la signature. Sinon, l'objet `next` sera +interprété comme un middleware normal et ne gérera pas les erreurs. + + + +Définissez les fonctions du middleware de la même manière que les autres fonctions du middleware, sauf avec quatre arguments au lieu de trois, spécifiquement avec la signature `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Quelque chose s'est cassé !'); +}); +``` + +Pour plus de détails sur la gestion des erreurs du middleware, voir : [Gestion des erreurs](/en/guide/error-handling). + +## middleware intégré + +À partir de la version 4.x, Express ne dépend plus de [Connect](https://github.com/senchalabs/connect). Les fonctions du middleware +qui étaient précédemment incluses avec Express sont maintenant dans des modules séparés ; voir [la liste des fonctions du middleware] (https://github.com/senchalabs/connect#middleware). + +Express a les fonctions internes suivantes : + +* [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. +* [express.json](/en/5x/api#express.json) analyse les requêtes entrantes avec des charges utiles JSON. **NOTE : Disponible avec Express 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) analyse les requêtes entrantes avec des charges utiles encodées en URL. **NOTE : Disponible avec Express 4.16.0+** + +## middleware de tierce partie + +Utilisez des logiciels tiers pour ajouter des fonctionnalités aux applications Express. + +Installez le module Node.js pour la fonctionnalité requise, puis chargez-le dans votre application au niveau de l'application ou au niveau du routeur. + +L'exemple suivant illustre l'installation et le chargement de la fonction middleware d'analyse de cookies `cookie-parser`. + +```bash +$ npm install cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// charge le middleware +app.use(cookieParser()); +``` + +Pour une liste partielle des fonctions middleware tierces qui sont couramment utilisées avec Express, voir : [middleware de tierce] (../resources/middleware). diff --git a/src/content/docs/fr/4x/guide/using-template-engines.mdx b/src/content/docs/fr/4x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..581a2b0cca --- /dev/null +++ b/src/content/docs/fr/4x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Utiliser les moteurs de gabarits avec Express +description: Découvrez comment intégrer et utiliser des moteurs de gabarits tels que Pug, Handlebars et EJS avec Express.js pour rendre les pages HTML dynamiques efficacement. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Un *moteur de modèle* vous permet d'utiliser des fichiers de modèles statiques dans votre application. Lors de l'exécution, le moteur de gabarit remplace les variables +dans un fichier de gabarit par des valeurs réelles, et transforme le modèle en un fichier HTML envoyé au client. +Cette approche facilite la conception d'une page HTML. + +Le [générateur d'application Express](/en/starter/generator) utilise [Pug](https://pugjs.org/api/getting-started.html) par défaut, mais il supporte aussi [Handlebars](https://www.npmjs.com/package/handlebars), et [EJS](https://www.npmjs.com/package/ejs), entre autres. + +Pour afficher les fichiers de gabarit, définissez les [propriétés de réglage de l'application](/en/4x/api#app.set), dans le `app.js` par défaut créé par le générateur: + +* `views`, le répertoire où se trouvent les fichiers de modèle. Ex. : `app.set('vues', './views')`. + Par défaut, le répertoire `views` se trouve à la racine de l'application. +* `voir le moteur`, le moteur de gabarit à utiliser. Par exemple, pour utiliser le moteur de gabarit Pug : `app.set('moteur de vue', 'pug')`. + +Ensuite, installez le paquet npm correspondant au moteur de gabarits ; par exemple pour installer Pug: + +```bash +$ npm install pug --save +``` + + +Les moteurs de gabarits conformes à la norme Express tels que Pug exportent une fonction nommée `__express(filePath, options, callback)`, +qui `res.render()` appelle pour rendre le code du gabarit. + +Certains moteurs de gabarits ne suivent pas cette convention. La bibliothèque [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +suit cette convention en mappant tous les moteurs de gabarits populaires Node.js, et fonctionne donc parfaitement dans Express. + + + +Une fois que le moteur de vue est défini, vous n'avez pas à spécifier le moteur ou charger le module moteur de gabarit dans votre application ; +Express charge le module en interne, par exemple : + +```js +app.set('moteur d'affichage', 'pug'); +``` + +Ensuite, créez un fichier de modèle Pug nommé `index.pug` dans le dossier `views`, avec le contenu suivant: + +```pug +html + devant + title= titre + corps + h1= message +``` + +Créez une route pour afficher le fichier `index.pug`. Si la propriété `view engine` n'est pas définie, +vous devez spécifier l'extension du fichier `view`. Sinon, vous pouvez l'oublier. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Bonjour !' }); +}); +``` + +Lorsque vous faites une requête sur la page d'accueil, le fichier `index.pug` sera rendu en HTML. + +Le cache du moteur de vue ne cache pas le contenu de la sortie du modèle, seulement le modèle sous-jacent. La vue est toujours rendue à chaque requête, même lorsque le cache est activé. diff --git a/src/content/docs/fr/4x/guide/writing-middleware.mdx b/src/content/docs/fr/4x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..06237ba1ee --- /dev/null +++ b/src/content/docs/fr/4x/guide/writing-middleware.mdx @@ -0,0 +1,239 @@ +--- +title: Écriture de middleware pour utilisation dans les applications Express +description: Apprenez à écrire des fonctions personnalisées de middleware pour les applications Express.js, y compris des exemples et des pratiques exemplaires pour améliorer la gestion des requêtes et des réponses. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Les fonctions *Middleware* sont des fonctions qui ont accès à l'objet [request object](/en/5x/api#req) (`req`), l'objet [réponse](/en/5x/api#res) (`res`), et la fonction `next` dans le cycle de réponse de l'application. La fonction `next` est une fonction dans le routeur Express qui, lorsqu'elle est appelée, exécute le middleware qui succède au middleware actuel. + +Les fonctions Middleware peuvent effectuer les tâches suivantes : + +* Exécuter n'importe quel code. +* Effectuez des modifications à la requête et aux objets de réponse. +* Termine le cycle de réponse de la requête. +* Appelez le prochain middleware dans la pile. + +Si la fonction middleware actuelle ne met pas fin au cycle de réponse de requête, elle doit appeler `next()` pour passer le contrôle à la prochaine fonction du middleware. Sinon, la demande sera laissée en suspens. + +La figure suivante montre les éléments d'un appel de fonction middleware : + +
+ + + + + +
+Éléments d'un appel de fonction middleware + +
méthode HTTP pour laquelle la fonction middleware s'applique.
+ +
+ Chemin (route) pour lequel la fonction middleware s'applique. +
+ +
+ La fonction middleware. +
+ +
+ Argument de rappel à la fonction middleware, appelé "next" par convention. +
+ +
+ L'argument HTTP réponse à la fonction middleware appelée "res" par convention + . +
+ +
HTTP demande argument à la fonction middleware appelée "req" par convention.
+
+
+ +À partir de Express 5, les fonctions middleware qui retournent une Promise appelleront `next(value)` quand elles rejettent ou lancent une erreur. `next` sera appelé avec la valeur rejetée ou avec l'erreur levée. + +## Exemple + +Voici un exemple de simple application "Hello World" Express. +Le reste de cet article va définir et ajouter trois fonctions middleware à l'application : +un appelé `myLogger` qui affiche un message de log simple. on appelle `requestTime` que +affiche l'horodatage de la requête HTTP, et un appelé `validateCookies` qui valide les cookies entrants. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +### Fonction Middleware myLogger + +Voici un exemple simple d'une fonction middleware appelée "myLogger". Cette fonction affiche seulement +"LOGGED" lorsqu'une requête vers l'application passe à travers elle. La fonction middleware est assignée à une variable +nommée `myLogger`. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +Notez l'appel ci-dessus à `next()`. Appeler cette fonction appelle la prochaine fonction du middleware dans +l'application. La fonction `next()` n'est pas une partie du noeud. s ou API Express, mais est le troisième argument +qui est passé à la fonction middleware. La fonction `next()` pourrait être nommée quoi que ce soit, +mais par convention elle est toujours nommée "next". Pour éviter toute confusion, utilisez toujours cette convention. + + + +Pour charger la fonction middleware, appelez `app.use()`, en spécifiant la fonction middleware. +Par exemple, le code suivant charge la fonction middleware `myLogger` avant la route vers le chemin racine (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console. og('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +Chaque fois que l'application reçoit une demande, elle affiche le message "LOGGGED" vers le terminal. + +L'ordre de chargement du middleware est important : les fonctions du middleware qui sont chargées en premier sont également exécutées en premier. + +Si `myLogger` est chargé après la route vers le chemin racine, la requête ne l'atteint jamais et l'application n'affiche pas "LOGGED", parce que le gestionnaire de route du chemin racine termine le cycle de réponse de requête. + +La fonction du middleware `myLogger` affiche simplement un message, passe ensuite la requête à la prochaine fonction middleware de la pile en appelant la fonction `next()`. + +### Middleware fonction requestTime + +Ensuite, nous allons créer une fonction middleware appelée "requestTime" et ajouter une propriété appelée `requestTime` +à l'objet requête. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +L'application utilise maintenant la fonction middleware `requestTime`. Aussi, la fonction callback de la route du chemin racine utilise la propriété que la fonction middleware ajoute à `req` (l'objet de requête). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req. equestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app. et('/', (req, res) => { + let responseText = 'Bonjour le monde!
'; + responseText += `Demandé à: ${req.requestTime}`; + res. end(responseText); +}); + +app.listen(3000); +``` + +Lorsque vous faites une demande à la racine de l'application, l'application affiche maintenant l'horodatage de votre requête dans le navigateur. + +### format@@0 Middleware function validateCookies + +Enfin, nous allons créer une fonction middleware qui valide les cookies entrants et envoie une réponse 400 si les cookies sont invalides. + +Voici un exemple de fonction qui valide les cookies avec un service asynchrone externe. + +```js +fonction async cookieValidator(cookies) { + essayer { + attendre externalyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Cookies invalides'); + } +} +``` + +Ici, nous utilisons le middleware [`cookie-parser`](/en/resources/middleware/cookie-parser) pour analyser les cookies entrants de l'objet `req` et les passer à notre fonction `cookieValidator`. Le middleware `validateCookies` retourne une Promesse que si le rejet déclenchera automatiquement notre gestionnaire d'erreurs. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('. cookieValidator'); + +const app = express(); + +fonction async validateCookies(req, res, next) { + attendent cookieValidator(req. ookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// gestionnaire d'erreur +app. se(err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Notez comment `next()` est appelé après `wait cookieValidator(req.cookies)`. Cela garantit que si +`cookieValidator` résoud, le prochain middleware de la pile sera appelé. Si vous passez quelque chose +à la fonction `next()` (sauf la chaîne `'route'` ou `'router'`), Express considère que la requête +actuelle est une erreur et ignorera toute fonction de routage et de middleware +qui ne gère pas les autres fonctions de routage. + + + +Parce que vous avez accès à l'objet requête, à l'objet de réponse, à la prochaine fonction du middleware dans la pile, et à l'ensemble du nœud. s API, les possibilités avec les fonctions du middleware sont infinies. + +Pour plus d'informations sur le middleware Express, voir : [Utiliser un middleware Express](/en/guide/using-middleware). + +## Logiciel middleware configurable + +Si vous avez besoin que votre middleware soit configurable, exportez une fonction qui accepte un objet d'options ou d'autres paramètres, qui retourne ensuite l'implémentation du middleware en fonction des paramètres d'entrée. + +Fichier: `my-middleware.js` + +```js +module. xports = function (options) { + fonction de retour (req, res, next) { + // Implémente la fonction middleware basée sur l'objet d'options + next(); + }; +}; +``` + +Le middleware peut maintenant être utilisé comme montré ci-dessous. + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Reportez-vous à [cookie-session](https://github.com/expressjs/cookie-session) et [compression](https://github.com/expressjs/compression) pour des exemples de middleware configurables. diff --git a/src/content/docs/fr/4x/starter/basic-routing.mdx b/src/content/docs/fr/4x/starter/basic-routing.mdx new file mode 100644 index 0000000000..1259c9d112 --- /dev/null +++ b/src/content/docs/fr/4x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Routage de base +description: Apprenez les fondamentaux du routage dans les applications Express.js, y compris comment définir des routes, gérer des méthodes HTTP et créer des gestionnaires de routes pour votre serveur web. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* désigne la façon dont une application répond à une requête client à un point de terminaison particulier, qui est une URI (ou un chemin) et une méthode spécifique de requête HTTP (GET, POST, etc.). + +Chaque route peut avoir une ou plusieurs fonctions de gestionnaire, qui sont exécutées lorsque la route est correspondante. + +La définition de la route prend la structure suivante : + +```js +app.METHOD(PATH, HANDLER); +``` + +Où : + +* `app` est une instance de `express`. +* `METHOD` est une [méthode de requête HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), en minuscule. +* `PATH` est un chemin sur le serveur. +* `HANDLER` est la fonction exécutée lorsque la route est correspondante. + + + +This tutorial assumes that an instance of `express` named `app` is created and the server is +running. Si vous n'êtes pas familier avec la création d'une application et son démarrage, consultez l'exemple Bonjour le monde +. + + + +Les exemples suivants illustrent la définition de routes simples. + +Répondez avec `Hello World!` sur la page d'accueil: + +```js +app.get('/', (req, res) => { + res.send('Hello World!'); +}); +``` + +Répondre à une requête POST sur la route racine (`/`), la page d'accueil de l'application : + +```js +app.post('/', (req, res) => { + res.send('Requête POST'); +}); +``` + +Répondre à une requête PUT sur la route `/user`: + +```js +app.put('/user', (req, res) => { + res.send('Requête PUT à /user'); +}); +``` + +Répondre à une requête DELETE sur la route `/user`: + +```js +app.delete('/user', (req, res) => { + res.send('Requête DELETE à /user'); +}); +``` + +Pour plus de détails sur le routage, consultez le [guide de routage] (/en/guide/routing). diff --git a/src/content/docs/fr/4x/starter/examples.mdx b/src/content/docs/fr/4x/starter/examples.mdx new file mode 100644 index 0000000000..3ab740ea07 --- /dev/null +++ b/src/content/docs/fr/4x/starter/examples.mdx @@ -0,0 +1,45 @@ +--- +title: Exemples Express +description: Explorez une collection d'exemples d'applications Express.js couvrant divers cas d'utilisation, intégrations et configurations avancées pour vous aider à apprendre et à construire vos projets. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Authentification avec login et mot de passe +* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - négociation de contenu HTTP +* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Working with cookie-based sessions +* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Working with cookies +* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transfert de fichiers vers le client +* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Travailler avec un modèle JavaScript embarqué (ejs) +* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Création des pages d'erreur +* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Travailler avec un middleware d'erreur +* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Gestionnaire de requêtes simple +* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown comme moteur de gabarit +* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Travailler avec plusieurs routeurs Express +* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - Contrôleurs de style MVC +* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Suivi de l'activité de l'utilisateur en ligne avec les paquets `online` et `redis` +* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Travailler avec les paramètres de la route +* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Opérations HTTP multiples sur la même ressource +* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organiser des routes à l'aide d'une carte +* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Travailler avec le middleware de route +* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organiser des routes par ressource +* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Search API +* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - Sessions utilisateur +* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Servir des fichiers statiques +* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Working with virtual hosts +* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Rendu dynamique des vues +* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Enregistrement des données dans l'objet de requête entre les appels de middleware +* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Service API simple + +## Exemples supplémentaires + +Ce sont quelques exemples supplémentaires avec des intégrations plus étendues. + + + Cette information se réfère à des sites tiers, des produits ou des modules tiers qui ne sont pas maintenus par l'équipe + Expressjs. La liste ci-dessous ne constitue pas une approbation ou une recommandation de l'équipe du projet + Expressjs. + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Application Fullstack avec Express et Next.js en utilisant [Prisma](https://www.npmjs.com/package/prisma) en tant qu'ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API avec Express in TypeScript en utilisant [Prisma](https://www.npmjs.com/package/prisma) en tant qu'ORM diff --git a/src/content/docs/fr/4x/starter/faq.md b/src/content/docs/fr/4x/starter/faq.md new file mode 100644 index 0000000000..494c74698b --- /dev/null +++ b/src/content/docs/fr/4x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: Foire Aux Questions +description: Retrouvez les réponses aux questions les plus fréquemment posées sur Express.js, y compris les sujets sur la structure de l'application, les modèles, l'authentification, les moteurs de gabarit, la gestion des erreurs, et plus encore. +--- + +## Comment structurer ma candidature ? + +Il n'y a pas de réponse définitive à cette question. La réponse dépend +de l'échelle de votre candidature et de l'équipe impliquée. To be as +flexible as possible, Express makes no assumptions in terms of structure. + +Les routes et autres logiques spécifiques à une application peuvent vivre dans autant de fichiers +que vous le souhaitez, dans n'importe quelle structure de répertoire que vous préférez. View the following +examples for inspiration: + +- [Liste des itinéraires](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Route map](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Il y a également des extensions tierces pour Express, qui simplifient certains de ces modèles: + +- [Itinéraire de ressource](https://github.com/expressjs/express-resource) + +## Comment définir des modèles? + +Express n'a aucune notion de base de données. This concept is +left up to third-party Node modules, allowing you to +interface with nearly any database. + +Voir [LoopBack](http://loopback.io) pour un framework basé sur Express, centré autour de modèles. + +## Comment puis-je authentifier les utilisateurs ? + +Authentication is another opinionated area that Express does not +venture into. Vous pouvez utiliser n'importe quel schéma d'authentification que vous souhaitez. +Pour un simple nom d'utilisateur / schéma de mot de passe, voir [cet exemple](https://github.com/expressjs/express/tree/master/examples/auth). + +## Quels moteurs de gabarits sont supportés par Express ? + +Express prend en charge tout moteur de gabarit qui est conforme à la signature `(path, locals, callback)`. +Pour normaliser les interfaces du moteur de gabarits et la mise en cache, consultez le projet +[consolidate.js](https://github.com/visionmedia/consolidate.js) +pour plus de support. Les moteurs de gabarits non listés peuvent toujours supporter la signature Express. + +Pour plus d'informations, voir [Utilisation de moteurs de gabarits avec Express](/en/guide/using-template-engines). + +## Comment gérer 404 réponses? + +Dans Express, 404 réponses ne sont pas le résultat d'une erreur, donc +le middleware de gestion d'erreurs ne les capturera pas. Ce comportement est +car une réponse 404 indique simplement l'absence de travail supplémentaire à faire ; +en d'autres termes, Express a exécuté toutes les fonctions et routes du middleware, +et a trouvé qu'aucun d'eux n'a répondu. All you need to +do is add a middleware function at the very bottom of the stack (below all other functions) +to handle a 404 response: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Ajoute des routes dynamiquement à l'exécution sur une instance de `express.Router()` +afin que les routes ne soient pas remplacées par une fonction de middleware. + +## Comment configurer un gestionnaire d'erreur ? + +Vous définissez le middleware de la même manière que les autres middleware, +sauf avec quatre arguments au lieu de trois; spécifiquement avec la signature `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Pour plus d'informations, voir [Gestion des erreurs] (/en/guide/error-handling). + +## Comment rendre le HTML simple ? + +Vous ne le faites pas! Il n'y a pas besoin de "render" HTML avec la fonction `res.render()`. +Si vous avez un fichier spécifique, utilisez la fonction `res.sendFile()`. +Si vous utilisez beaucoup d'actifs depuis un répertoire, utilisez la fonction `express.static()` +middleware. + +## Quelle version de Node.js est requise ? + +- [Express 4.x](/en/4x/api) nécessite Node.js 0.10 ou supérieur. +- [Express 5.x](/en/5x/api) nécessite Node.js 18 ou plus. diff --git a/src/content/docs/fr/4x/starter/generator.mdx b/src/content/docs/fr/4x/starter/generator.mdx new file mode 100644 index 0000000000..fdfd9b4883 --- /dev/null +++ b/src/content/docs/fr/4x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Générateur d'application Express +description: Apprenez à utiliser l'outil de générateur d'applications Express pour créer rapidement un squelette pour vos applications Express.js, en rationalisant la configuration et la configuration. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Utilisez l'outil de générateur d'applications, `express-generator`, pour créer rapidement un squelette d'application. + +Vous pouvez exécuter le générateur d'application avec la commande `npx` (disponible dans Node.js 8.2.0). + +```bash +Générateur de npx express $ +``` + +Pour les versions antérieures de Node, installez le générateur d'application en tant que paquet npm global puis lancez le : + +```bash +$ npm install -g express-generator +$ express +``` + +Affiche les options de la commande avec l'option `-h`: + +```bash +$ express -h + + Utilisation : express [options] [dir] + + Options : + + -h, --help affiche les informations d'utilisation + --version affiche le numéro de version + -e, --ejs add ejs engine support + --hbs add handlebar engine support + --pug add pug engine support + -H, --hogan add hogan. le support du moteur + --no-view générer sans afficher le moteur + -v, --view ajouter la vue support (ejs|hbs|hjs|jade|pug|twig|vash) (par défaut jade) + -c, --css ajoute la feuille de style support (moins|stylus|compass|sass) (par défaut, css simple) + --git add . itignore + -f, --force sur un répertoire non vide +``` + +Par exemple, ce qui suit crée une application Express nommée *myapp*. L'application sera créée dans un dossier nommé *myapp* dans le répertoire de travail actuel et le moteur de vue sera réglé sur Pug: + +```bash +$ express --view=pug myapp + + create : myapp + create : myapp/package.json + create : myapp/app. s + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index. s + créer : monapp/routes/utilisateurs. s + créer : myapp/public/stylesheets + create : myapp/public/stylesheets/style. ss + create : myapp/views + create : myapp/views/index. ug + create : myapp/views/layout.pug + create : myapp/views/error. ug + create : monapp/bin + create : myapp/bin/www +``` + +Installez ensuite les dépendances : + +```bash +$ cd myapp +$ npm install +``` + +Sous MacOS ou Linux, exécutez l'application avec cette commande : + +```bash +$ DEBUG=myapp:* npm start +``` + +Sous l'invite de commande Windows, utilisez cette commande : + +```bash +> set DEBUG=myapp:* & npm start +``` + +Sous Windows PowerShell, utilisez cette commande : + +```bash +PS> $env:DEBUG='myapp:*'; npm start +``` + +Ensuite, chargez `http://localhost:3000/` dans votre navigateur pour accéder à l'application. + +L'application générée a la structure de répertoire suivante : + +```bash +. +── app.js +── bin +文 ─ www +── package. fils +── public +Ω─ images +Ω─ javascripts +文 ── feuilles de style +Ω ─ style. ss +── routes +文── index.js +Ω ── utilisateurs. s + ── vues + ── erreur. ug + ── index.pug + ─ layout.pug + +7 répertoires, 9 fichiers +``` + + + +La structure d'application créée par le générateur n'est qu'un des nombreux moyens de structurer les applications Express. +N'hésitez pas à utiliser cette structure ou à la modifier pour mieux répondre à vos besoins. + + diff --git a/src/content/docs/fr/4x/starter/hello-world.mdx b/src/content/docs/fr/4x/starter/hello-world.mdx new file mode 100644 index 0000000000..8e38e29de6 --- /dev/null +++ b/src/content/docs/fr/4x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Bonjour l'exemple du monde +description: Commencez avec Express.js en construisant une simple application 'Hello World', en démontrant la configuration de base et la création de serveurs pour les débutants. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Intégré ci-dessous est essentiellement l'application Express la plus simple que vous puissiez créer. C'est une seule application de fichier +— *pas* ce que vous obtiendrez si vous utilisez le [générateur Express](/en/starter/generator), que +crée l'échafaudage pour une application complète avec de nombreux fichiers JavaScript, des modèles Jade, et des sous-répertoires +à diverses fins. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res. end('Hello World!'); +}); + +app.listen(port, () => { + console.log(`Exemple d'application d'écoute sur le port ${port}`); +}); +``` + +Cette application démarre un serveur et écoute le port 3000 pour les connexions. L'application répond avec "Hello World!" pour les demandes +à l'URL racine (`/`) ou *route*. Pour tous les autres chemins, il répondra avec un **404 Not Found**. + +## Exécution locale + +Créez d'abord un répertoire nommé `myapp`, changez et exécutez `npm init`. Ensuite, installez `express` en tant que dépendance, conformément au [guide d'installation](/en/starter/installing). + +Dans le dossier `myapp`, créez un fichier nommé `app.js` et copiez le code à partir de l'exemple ci-dessus. + + + +Les `req` (request) et `res` (response) sont les mêmes objets que le noeud fournit, donc vous pouvez +appeler `req. ipe()`, `req.on('data', callback)`, et tout autre chose que vous feriez sans Express +impliqué. + + + +Exécutez l'application avec la commande suivante : + +```bash +$ node app.js +``` + +Ensuite, chargez `http://localhost:3000/` dans un navigateur pour voir la sortie. diff --git a/src/content/docs/fr/4x/starter/installing.mdx b/src/content/docs/fr/4x/starter/installing.mdx new file mode 100644 index 0000000000..2383a5c05f --- /dev/null +++ b/src/content/docs/fr/4x/starter/installing.mdx @@ -0,0 +1,50 @@ +--- +title: Installation en cours +description: Apprenez à installer Express.js dans votre environnement Node.js, y compris la configuration de votre répertoire de projet et la gestion des dépendances avec npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Avant de commencer, assurez-vous que vous avez [Node.js](https://nodejs.org/) 0.10 ou supérieur installé. Ensuite, créez un répertoire pour votre application et naviguez dedans. + +```bash +mkdir myapp +cd myapp +``` + +Utilisez la commande `npm init` pour créer un fichier `package.json` pour votre application. +Pour plus d'informations sur le fonctionnement de `package.json`, voir [Specifics of npm's package.json handling](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +Cette commande vous invite à trouver un certain nombre de choses, telles que le nom et la version de votre application. +Pour l'instant, vous pouvez simplement appuyer sur RETURN pour accepter les valeurs par défaut pour la plupart d'entre eux, à l'exception de la règle suivante : + +``` +point d'entrée: (index.js) +``` + +Entrez `app.js`, ou quel que soit le nom du fichier principal. Si vous voulez qu'il soit `index.js`, appuyez sur RETURN pour accepter le nom de fichier par défaut suggéré. + +Maintenant, installez Express dans le répertoire `myapp` et sauvegardez-le dans la liste des dépendances. Par exemple : + +```bash +npm installation express +``` + +Pour installer Express temporairement et ne pas l'ajouter à la liste des dépendances : + +```bash +npm install express --no-save +``` + + + +Par défaut avec la version npm 5.0+, `npm install` ajoute le module à la liste `dependencies` dans le paquet +`. son`; avec les versions antérieures de npm, vous devez spécifier explicitement l'option `--save` +. Puis, par la suite, exécuter `npm install` dans le répertoire de l'application sera automatiquement +installer des modules dans la liste des dépendances. + + diff --git a/src/content/docs/fr/4x/starter/static-files.mdx b/src/content/docs/fr/4x/starter/static-files.mdx new file mode 100644 index 0000000000..041757b116 --- /dev/null +++ b/src/content/docs/fr/4x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Servir les fichiers statiques dans Express +description: Comprendre comment servir les fichiers statiques comme les images, CSS, et JavaScript dans les applications Express.js en utilisant le middleware 'statique' intégré. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Pour servir des fichiers statiques tels que des images, des fichiers CSS et des fichiers JavaScript, utilisez la fonction middleware intégrée `express.static` dans Express. + +La signature de la fonction est : + +```js +express.static(root, [options]); +``` + +L'argument `root` spécifie le répertoire racine à partir duquel servir les actifs statiques. +Pour plus d'informations sur l'argument `options`, voir [express.static](/en/5x/api#express.static). + +Par exemple, utilisez le code suivant pour servir les images, les fichiers CSS et JavaScript dans un répertoire nommé `public`: + +```js +app.use(express.static('public')); +``` + +Maintenant, vous pouvez charger les fichiers qui se trouvent dans le répertoire `public`: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express recherche les fichiers relatifs au répertoire statique, donc le nom du répertoire statique +ne fait pas partie de l'URL. + + + +Pour utiliser plusieurs répertoires statiques, appelez la fonction middleware `express.static` plusieurs fois : + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express recherche les fichiers dans l'ordre dans lequel vous définissez les répertoires statiques avec la fonction `express.static`. + + + +Pour de meilleurs résultats, utilisez un proxy +inversé pour améliorer les performances de +servant des actifs statiques. + + + +Pour créer un préfixe de chemin virtuel (où le chemin n'existe pas dans le système de fichiers) pour les fichiers qui sont servis par le fichier `express. fonction tatic`, [spécifiez un chemin de montage](/en/5x/api#app.use) pour le répertoire statique, comme indiqué ci-dessous: + +```js +app.use('/static', express.static('public')); +``` + +Maintenant, vous pouvez charger les fichiers qui se trouvent dans le dossier `public` à partir du préfixe de chemin `/static`. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +Cependant, le chemin que vous fournissez à la fonction `express.static` est relatif au répertoire depuis lequel vous lancez votre processus `node`. Si vous exécutez l'application express à partir d'un autre répertoire, il est plus sûr d'utiliser le chemin absolu du répertoire que vous voulez servir: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public'))); +``` + +Pour plus de détails sur la fonction `serve-static` et ses options, voir [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/fr/5x/advanced/developing-template-engines.md b/src/content/docs/fr/5x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..8ddb890522 --- /dev/null +++ b/src/content/docs/fr/5x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Développement de moteurs de gabarits pour Express +description: Apprenez comment développer des moteurs de gabarits personnalisés pour Express.js en utilisant app.engine(), avec des exemples sur la création et l'intégration de votre propre logique de rendu de gabarits. +--- + +Utilisez la méthode `app.engine(ext, callback)` pour créer votre propre moteur de template. `ext` fait référence à l'extension de fichier, et `callback` est la fonction du moteur de gabarit, qui accepte les éléments suivants comme paramètres: l'emplacement du fichier, l'objet d'options et la fonction de rappel. + +Le code suivant est un exemple d'implémenter un moteur de gabarit très simple pour le rendu des fichiers `.ntl`. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +Votre application sera maintenant en mesure d'afficher les fichiers `.ntl`. Créez un fichier nommé `index.ntl` dans le dossier `views` avec le contenu suivant. + +```pug +#title# +#message# +``` + +Ensuite, créez la route suivante dans votre application. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +Lorsque vous faites une requête sur la page d'accueil, `index.ntl` sera rendu en HTML. diff --git a/src/content/docs/fr/5x/guide/behind-proxies.mdx b/src/content/docs/fr/5x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..1eabee667b --- /dev/null +++ b/src/content/docs/fr/5x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Exprimez derrière les mandataires +description: Apprenez à configurer les applications Express.js pour qu'elles fonctionnent correctement derrière les mandataires inversés, y compris en utilisant le paramètre proxy de confiance pour gérer les adresses IP du client. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Lorsque vous exécutez une application Express derrière un proxy inverse, certaines des API Express peuvent retourner des valeurs différentes de celles attendues. Pour ajuster pour cela, le paramètre `trust proxy` de l'application peut être utilisé pour exposer des informations fournies par le proxy inverse dans les API Express. Le problème le plus courant est les API express qui exposent l'adresse IP du client peut à la place afficher une adresse IP interne du proxy inverse. + + + +Lors de la configuration du paramètre `trust proxy`, il est important de comprendre la configuration exacte du proxy inverse +. Puisque ce paramètre fera confiance aux valeurs fournies dans la requête, Il est important que +la combinaison du paramètre dans Express corresponde à la façon dont le proxy inversé fonctionne. + + + +Le paramètre de l'application `trust proxy` peut être défini à l'une des valeurs listées dans la table suivante. + + + + + + + + + + + + + + + + + + + + + +
TypeValeur
Boolean +Si `true`, l'adresse IP du client est comprise comme l'entrée la plus à gauche dans l'en-tête `X-Forwarded-For`. + +Si `false`, l'application est comprise comme faisant directement face au client et l'adresse IP du client est dérivée de `req.socket.remoteAddress`. Ceci est le paramètre par défaut. + + +Lorsque vous définissez sur `true`, il est important de s'assurer que le dernier proxy inversé fiable est de supprimer/écraser tous les en-têtes HTTP suivants : `X-Forwarded-For`, `X-Forwarded-Host`, et `X-Forwarded-Proto`, sinon il sera possible pour le client de fournir n'importe quelle valeur. + +
Adresses IP +Une adresse IP, un sous-réseau ou un tableau d'adresses IP et de sous-réseaux à confier comme étant un proxy inverse. La liste suivante montre les noms de sous-réseaux pré-configurés : + +* loopback - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +Vous pouvez définir les adresses IP de l'une des façons suivantes : + +```js +app.set('trust proxy', 'loopback'); // specify a single subnet +app.set('trust proxy', 'loopback, 123.123.123.123'); // specify a subnet and an address +app.set('trust proxy', 'loopback, linklocal, uniquelocal'); // specify multiple subnets as CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // specify multiple subnets as an array +``` + +Lorsqu'il est spécifié, les adresses IP ou les sous-réseaux sont exclus du processus de détermination de l'adresse, et l'adresse IP non fiable la plus proche du serveur d'application est déterminée comme l'adresse IP du client. Cela fonctionne en vérifiant si `req.socket.remoteAddress` est fiable. Si c'est le cas, alors chaque adresse dans `X-Forwarded-For` est vérifiée de droite à gauche jusqu'à la première adresse non fiable. + +
Nombre +Utilisez l'adresse qui est au plus `n` nombre de sauts loin de l'application Express. `req.socket.remoteAddress` est le premier saut, et le reste est recherché dans l'en-tête `X-Forwarded-For` de droite à gauche. Une valeur de `0` signifie que la première adresse non fiable serait `req.socket.remoteAddress`, c'est-à-dire qu'il n'y a pas de proxy inverse. + + +Lors de l'utilisation de ce paramètre, il est important de s'assurer qu'il n'y a pas de multiples, chemins différents vers l'application Express de sorte que le client peut être inférieur au nombre de sauts configurés, sinon il pourrait être possible pour le client de fournir n'importe quelle valeur. + +
Fonction +Implémentation de confiance personnalisée. + +```js +app.set('trust proxy', (ip) => { + if (ip === '127.0.0.1' || ip === '123.123.123. 23') + retourne true; // les adresses IP + approuvées retournent false; +}); +``` + +
+ +Activer `trust proxy` aura l'impact suivant : + +
    +
  • + La valeur de [req.hostname](/en/api#req.hostname) est dérivée de la valeur définie dans l'en-tête + `X-Forwarded-Host`, qui peut être définie par le client ou par le proxy. +
    • +
  • + `X-Forwarded-Proto` peut être défini par le proxy inverse pour dire à l'application si c'est `https` ou + `http` ou même un nom invalide. Cette valeur est reflétée par [req.protocol](/en/api#req.protocol). +
    • +
  • + Les valeurs [req.ip](/en/api#req.ip) et [req.ips](/en/api#req.ips) sont remplies en fonction de l'adresse du socket + et de l'en-tête `X-Forwarded-For`, à partir de la première adresse non fiable. +
    • +
+ +Le paramètre `trust proxy` est implémenté en utilisant le paquet [proxy-addr](https://www.npmjs.com/package/proxy-addr). Pour plus d'informations, voir sa documentation. diff --git a/src/content/docs/fr/5x/guide/debugging.mdx b/src/content/docs/fr/5x/guide/debugging.mdx new file mode 100644 index 0000000000..04a54bbf25 --- /dev/null +++ b/src/content/docs/fr/5x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Débogage Express +description: Apprenez comment activer et utiliser les journaux de débogage dans les applications Express.js en définissant la variable d'environnement DEBUG pour un dépannage amélioré. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Pour voir tous les journaux internes utilisés dans Express, définissez la variable d'environnement `DEBUG` à +`express:*` lors du lancement de votre application. + +```bash +$ DEBUG=express:* node index.js +``` + +Sous Windows, utilisez la commande correspondante. + +```bash +> $env:DEBUG = "express:*"; node index.js +``` + +L'exécution de cette commande sur l'application par défaut générée par le [générateur express](/en/starter/generator) affiche la sortie suivante: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +Lorsqu'une demande est faite à l'application, vous verrez les journaux spécifiés dans le code Express: + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index. ug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +Pour voir les logs uniquement à partir de l'implémentation du routeur, définissez la valeur de `DEBUG` à `express:router`. De même, pour ne voir que les logs de l'implémentation de l'application, définissez la valeur de `DEBUG` à `express:application`, et ainsi de suite. + +## Applications générées par `express` + +Une application générée par la commande `express` utilise le module `debug` et son espace de noms de débogage est limité au nom de l'application. + +Par exemple, si vous avez généré l'application avec `$ express sample-app`, vous pouvez activer les instructions de débogage avec la commande suivante : + +```bash +$ DEBUG=sample-app:* node ./bin/www +``` + +Vous pouvez spécifier plus d'un espace de noms de débogage en assignant une liste de noms séparés par des virgules : + +```bash +$ DEBUG=http,mail,express:* node index.js +``` + +## Options avancées + +Lors de l'exécution de Node.js, vous pouvez définir quelques variables d'environnement qui changeront le comportement du journal de débogage : + +| Nom | Objectif | +| ------------------- | ---------------------------------------------------------------- | +| `DEBUG` | Active/désactive les espaces de noms de débogage spécifiques. | +| `DEBUG_COLORS` | Utiliser ou non les couleurs dans la sortie de débogage. | +| `DEBUG_DEPTH` | Profondeur de l'inspection des objets. | +| `DEBUG_FD` | Descripteur de fichier vers lequel écrire la sortie de débogage. | +| `DEBUG_SHOW_HIDDEN` | Affiche les propriétés masquées sur les objets inspectés. | + + + +Les variables d'environnement commençant par `DEBUG_` finissent par être converties en un objet d'options +qui est utilisé avec les formats `%o`/`%O`. Voir la documentation Node.js pour +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) pour la liste complète +. + + diff --git a/src/content/docs/fr/5x/guide/error-handling.mdx b/src/content/docs/fr/5x/guide/error-handling.mdx new file mode 100644 index 0000000000..1ef9f11421 --- /dev/null +++ b/src/content/docs/fr/5x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Gestion des erreurs +description: Comprenez comment Express.js gère les erreurs dans le code synchrone et asynchrone et apprend à implémenter la gestion des erreurs personnalisées pour vos applications. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Error Handling* fait référence à la façon dont Express attrape et traite les erreurs que +se produisent de manière synchronisée et asynchrone. Express comes with a default error +handler so you don't need to write your own to get started. + +## Erreurs de capture + +Il est important de s'assurer qu'Express attrape toutes les erreurs qui se produisent lorsque +exécute des gestionnaires de routes et des middleware. + +Les erreurs qui se produisent dans le code synchrone dans les gestionnaires de route et les middleware +ne nécessitent aucun travail supplémentaire. If synchronous code throws an error, then Express will +catch and process it. Par exemple : + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Express va attraper cela tout seul. +}); +``` + +For errors returned from asynchronous functions invoked by route handlers +and middleware, you must pass them to the `next()` function, where Express will +catch and process them. Par exemple : + +```js +app.get('/', (req, res, next) => { + fs. eadFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Passez des erreurs à Express. + } else { + res. end(data); + } + }); +}); +``` + +À partir de Express 5, les gestionnaires de route et les middleware qui retournent une Promise +appelleront automatiquement `next(value)` quand ils rejettent ou lancent une erreur. +Par exemple : + +```js +app.get('/user/:id', async (req, res, next) => { + const user = wait getUserById(req.params.id); + res.send(user); +}); +``` + +Si `getUserById` lance une erreur ou un rejet, `next` sera appelé avec soit +l'erreur émise ou la valeur rejetée. Si aucune valeur rejetée n'est fournie, `next` +sera appelée avec un objet Error par défaut fourni par le routeur Express. + +If you pass anything to the `next()` function (except the string `'route'`), +Express regards the current request as being an error and will skip any +remaining non-error handling routing and middleware functions. + +Si le callback dans une séquence ne fournit aucune donnée, seulement des erreurs, vous pouvez simplifier +ce code comme suit: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +Dans l'exemple ci-dessus, `next` est fourni comme callback pour `fs.writeFile`, +qui est appelé avec ou sans erreurs. S'il n'y a pas d'erreur, le second +est exécuté, sinon Express attrape et traite l'erreur. + +Vous devez attraper les erreurs qui se produisent dans le code asynchrone invoqué par les gestionnaires de route ou +middleware et les passer à Express pour le traitement. Par exemple : + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + essayez { + throw new Error('BROKEN'); + } attraper (err) { + next(err); + } + }, 100); +}); +``` + +L'exemple ci-dessus utilise un bloc `try...catch` pour attraper des erreurs dans le code +asynchrone et les passer à Express. Si le bloc `try...catch` +était omis, Express ne attrapera pas l'erreur car il ne fait pas partie du code du gestionnaire +synchrone. + +Utilise des promesses pour éviter les frais généraux du bloc `essayer...catch` ou lorsque tu utilises les fonctions +qui renvoient des promesses. Par exemple : + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + . hen(() => { + throw new Error('BROKEN'); + }) + . atch(next); // Les erreurs seront passées à Express. +}); +``` + +Puisque les promesses attrapent automatiquement à la fois les erreurs synchrones et les promesses rejetées, +vous pouvez simplement fournir `next` car le gestionnaire de capture final et Express attrapera des erreurs, +parce que le gestionnaire de capture est donné l'erreur comme premier argument. + +Vous pouvez également utiliser une chaîne de gestionnaires pour vous fier à l'erreur synchrone +attrapant, en réduisant le code asynchrone à quelque chose de trivial. Par exemple : + +```js +app.get('/', [ + function (req, res, next) { + fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals. ata = data; + next(err); + }); + }, + fonction (req, res) { + res. ocals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +L'exemple ci-dessus a quelques déclarations triviales de l'appel `readFile` +. Si `readFile` cause une erreur, alors il passe l'erreur à Express, sinon vous +revenez rapidement au monde de la gestion des erreurs synchrones dans le prochain gestionnaire +de la chaîne. Ensuite, l'exemple ci-dessus tente de traiter les données. Si cela échoue, alors le gestionnaire d'erreurs synchrone +l'attrapera. Si vous aviez fait ce traitement à l'intérieur de +la callback `readFile`, alors l'application pourrait quitter et les gestionnaires d'erreur +Express ne s'exécuteraient pas. + +Quelle que soit la méthode que vous utilisez, si vous voulez que les gestionnaires d'erreur Express soient appelés et que l'application +survive, vous devez vous assurer qu'Express reçoit l'erreur. + +## Le gestionnaire d'erreur par défaut + +Express est livré avec un gestionnaire d'erreur intégré qui prend en charge toutes les erreurs qui peuvent être rencontrées dans l'application. Cette fonction middleware par défaut est ajoutée à la fin de la pile de fonctions du middleware. + +Si vous passez une erreur à `next()` et que vous ne la gérez pas dans un gestionnaire d'erreur personnalisé +, il sera géré par le gestionnaire d'erreur intégré ; l'erreur sera +écrite au client avec la trace de la pile. La trace de la pile n'est pas incluse +dans l'environnement de production. + + + +Définissez la variable d'environnement `NODE_ENV` à `production`, pour exécuter l'application en mode production. + + + +Lorsqu'une erreur est écrite, les informations suivantes sont ajoutées à la réponse +: + +* Le `res.statusCode` est défini à partir de `err.status` (ou `err.statusCode`). Si + cette valeur est en dehors de la plage 4xx ou 5xx, elle sera définie à 500. +* Le `res.statusMessage` est défini selon le code de statut. +* Le corps sera le HTML du message de code de statut lorsque l'environnement de production + , sinon sera `err.stack`. +* N'importe quel en-tête spécifié dans un objet `err.headers`. + +Si vous appelez `next()` avec une erreur après avoir commencé à écrire la réponse +(par exemple, si vous rencontrez une erreur lors du streaming de la réponse +au client), le gestionnaire d'erreur par défaut Express ferme la connexion +et échoue la requête. + +Ainsi, lorsque vous ajoutez un gestionnaire d'erreurs personnalisé, vous devez déléguer à +le gestionnaire d'erreur Express par défaut, lorsque les en-têtes +ont déjà été envoyés au client : + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Notez que le gestionnaire d'erreur par défaut peut être déclenché si vous appelez `next()` avec une erreur +dans votre code plusieurs fois, même si une gestion personnalisée des erreurs est en place. + +D'autres erreurs de gestion du middleware peuvent être trouvées dans [middleware Express](/en/resources/middleware). + +## Écriture des gestionnaires d'erreurs + +Définissez les fonctions du middleware de la même manière que les autres fonctions du middleware, +excepté les fonctions de gestion des erreurs ont quatre arguments au lieu de trois: +`(err, req, res, next)`. Par exemple : + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Quelque chose s'est cassé !'); +}); +``` + +Vous définissez le middleware en dernier lieu, après d'autres appels `app.use()` et routage des appels; par exemple: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser. rlencoded({ + étendu: true, + }) +); +app.use(bodyParser.json()); +app. se(methodOverride()); +app.use((err, req, res, next) => { + // logique +}); +``` + +Les réponses provenant d'une fonction middleware peuvent être dans n'importe quel format, comme une page d'erreur HTML, un message simple ou une chaîne JSON. + +Pour des raisons organisationnelles (et pour un cadre de plus haut niveau), vous pouvez définir +plusieurs fonctions de gestion des erreurs du middleware, tout comme vous le feriez avec les fonctions +régulières du middleware. Par exemple, pour définir un gestionnaire d'erreurs +pour les requêtes faites en utilisant `XHR` et ceux sans : + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +application. se( + bodyParser.urlencoded({ + étendu: true, + }) +); +app. se(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +Dans cet exemple, les génériques `logErrors` peuvent écrire la requête et les informations d'erreur +à `stderr`, par exemple : + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +Aussi dans cet exemple, `clientErrorHandler` est défini comme suit ; dans ce cas, l'erreur est explicitement passée au suivant. + +Notez que lorsque *not* appelez "next" dans une fonction de gestion des erreurs, vous êtes responsable de l'écriture (et de la fin) de la réponse. Sinon, ces demandes seront « bloquées » et ne seront pas admissibles au ramassage des déchets. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500). end({ error: 'Quelque chose a échoué!' }); + } else { + next(err); + } +} +``` + +Implémenter la fonction "catch-all" `errorHandler` comme suit (par exemple): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +Si vous avez un gestionnaire de route avec plusieurs fonctions de rappel, vous pouvez utiliser le paramètre `route` pour passer au gestionnaire de route suivant. Par exemple : + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user. asPaid) { + // continue à gérer cette requête + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent. ind(err, doc) => { + if (err) return next(err); + res. son(doc); + }); + } +); +``` + +Dans cet exemple, le gestionnaire `getPaidContent` sera ignoré, mais tous les gestionnaires restants dans `app` pour `/a_route_behind_paywall` continueront d'être exécutés. + + + +Les appels à `next()` et `next(err)` indiquent que le gestionnaire actuel est complet et dans quel état. +`next(err)` sautera tous les gestionnaires restants de la chaîne, à l'exception de ceux qui sont configurés à +gérer les erreurs comme décrit ci-dessus. + + diff --git a/src/content/docs/fr/5x/guide/overriding-express-api.md b/src/content/docs/fr/5x/guide/overriding-express-api.md new file mode 100644 index 0000000000..fdd81c674a --- /dev/null +++ b/src/content/docs/fr/5x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Outrepasser l'API Express +description: Découvrez comment personnaliser et étendre l'API Express.js en écrasant les méthodes et les propriétés sur les objets de demande et de réponse à l'aide de prototypes. +--- + +L'API Express se compose de différentes méthodes et propriétés sur les objets de requête et de réponse. Celles-ci sont héritées du prototype. Il y a deux points d'extension pour l'API Express : + +1. Les prototypes globaux à `express.request` et `express.response`. +2. Prototypes spécifiques à l'application à `app.request` et `app.response`. + +Modifier les prototypes globaux affectera toutes les applications Express chargées dans le même processus. Si vous le souhaitez, les modifications peuvent être apportées à l'application en modifiant uniquement les prototypes spécifiques à l'application après avoir créé une nouvelle application. + +## Méthodes + +Vous pouvez remplacer la signature et le comportement des méthodes existantes avec vos propres méthodes en assignant une fonction personnalisée. + +Voici un exemple de surcharge du comportement de [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +L'implémentation ci-dessus modifie complètement la signature originale de `res.sendStatus`. Il accepte maintenant un code de statut, un type d'encodage, et le message à envoyer au client. + +La méthode surchargée peut maintenant être utilisée de cette manière: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## Propriétés + +Les propriétés de l'API Express sont soit : + +1. Propriétés assignées (ex: `req.baseUrl`, `req.originalUrl`) +2. Défini comme getters (ex: `req.secure`, `req.ip`) + +Puisque les propriétés de la catégorie 1 sont assignées dynamiquement sur les objets `request` et `response` dans le contexte du cycle de réponse de la requête courante, leur comportement ne peut pas être remplacé. + +Les propriétés de la catégorie 2 peuvent être écrasées en utilisant l'API des extensions API Express. + +Le code suivant réécrit comment la valeur de `req.ip` doit être dérivée. Maintenant, il retourne simplement la valeur de l'en-tête de la requête `Client-IP`. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Prototype + +Afin de fournir l'API Express, les objets de requête/réponse passés à Express (via `app(req, res)`, par exemple) doivent hériter de la même chaîne de prototypes. Par défaut, c'est `http.IncomingRequest.prototype` pour la requête et `http.ServerResponse.prototype` pour la réponse. + +Sauf si nécessaire, il est recommandé de le faire uniquement au niveau de l'application, plutôt qu'au niveau mondial. Veillez également à ce que le prototype utilisé corresponde le plus près possible à la fonctionnalité des prototypes par défaut. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/fr/5x/guide/routing.mdx b/src/content/docs/fr/5x/guide/routing.mdx new file mode 100644 index 0000000000..65e3d690e4 --- /dev/null +++ b/src/content/docs/fr/5x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Routage +description: Apprenez à définir et utiliser des routes dans les applications Express.js, y compris les méthodes de trajet, les chemins de trajet, les paramètres et l'utilisation du routeur pour le routage modulaire. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* indique comment les terminaux (URIs) d'une application répondent aux requêtes du client. +Pour une introduction au routage, voir [Routage de base](/en/starter/basic-routing). + +Vous définissez le routage à l'aide des méthodes de l'objet Express `app` qui correspondent aux méthodes HTTP; +par exemple, `app. et()` pour gérer les requêtes GET et `app.post` pour gérer les requêtes POST. Pour une liste complète, +voir [app.METHOD](/en/5x/api#app.METHOD). Vous pouvez également utiliser [app.all()](/en/5x/api#app.all) pour gérer toutes les méthodes HTTP et [app. se()](/en/5x/api#app.use) à +spécifient le middleware comme fonction de callback (Voir [Utilisation du middleware](/en/guide/using-middleware) pour plus de détails). + +Ces méthodes de routage spécifient une fonction de rappel (parfois appelée "fonctions de gestionnaire") appelée lorsque l'application reçoit une requête vers la route spécifiée (endpoint) et la méthode HTTP. En d'autres termes, l'application "écoute" les requêtes qui correspondent à la(les) route(s) spécifiée(s) et à la(les) méthode(s), et quand il détecte une correspondance, il appelle la fonction de rappel spécifiée. + +En fait, les méthodes de routage peuvent avoir plus d'une fonction de rappel en tant qu'arguments. +Avec plusieurs fonctions de rappel, il est important de fournir `next` comme argument à la fonction de callback puis appeler `next()` dans le corps de la fonction pour distribuer le contrôle +au prochain rappel. + +Le code suivant est un exemple de route très basique. + +```js +const express = require('express'); +const app = express(); + +// répond avec "bonjour le monde" lorsqu'une demande GET est faite à l'application +de la page d'accueil. et('/', (req, res) => { + res.send('bonjour le monde'); +}); +``` + +## Méthodes de la route + +Une méthode de route est dérivée d'une des méthodes HTTP, et est attachée à une instance de la classe `express`. + +Le code suivant est un exemple de routes qui sont définies pour le `GET` et les méthodes `POST` à la racine de l'application. + +```js +// Route de la méthode GET +app.get('/', (req, res) => { + res. end('Requête GET sur la page d'accueil'); +}); + +// La méthode POST route +app. ost('/', (req, res) => { + res.send('Requête POST sur la page d'accueil'); +}); +``` + +Express supporte les méthodes qui correspondent à toutes les méthodes de requête HTTP : `get`, `post`, et ainsi de suite. +Pour une liste complète, voir [app.METHOD](/en/5x/api#app.METHOD). + +Il y a une méthode de routage spéciale, `app.all()`, utilisée pour charger les fonctions du middleware à un chemin pour *toutes* les méthodes de requête HTTP. Par exemple, le gestionnaire suivant est exécuté pour les requêtes vers la route `"/secret"` si vous utilisez `GET`, `POST`, `PUT`, `DELETE`, ou toute autre méthode de requête HTTP supportée dans le module [http](https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Accéder à la section secrète ...'); + next(); // passer le contrôle au prochain gestionnaire +}); +``` + +## Chemins de la route + +Les chemins de la route, en combinaison avec une méthode de requête, définissent les points de terminaison à partir desquels les requêtes peuvent être faites. Les chemins de route peuvent être des chaînes, des chaînes de caractères ou des expressions régulières. + + + +En express 5, les caractères `? , `+`, `\*`, `[]`et `()\` sont gérés différemment de la version +4, veuillez consulter le [guide de migration](/en/guide/migrating-5#path-syntax) pour plus d'informations. + + + + + +Dans l'expression expresse 4, des caractères d'expression régulière tels que `$` doivent être échappés avec un `\`. + + + + + +Express utilise [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) pour correspondre aux chemins de la route +; consultez la documentation path-to-regexp pour toutes les possibilités dans la définition des chemins d'itinéraire. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) est un outil pratique pour +qui teste les routes Express de base, bien qu'il ne supporte pas la recherche de masques. + + + +Les chaînes de requête ne font pas partie du chemin de la route. + +### Chemins de route basés sur des chaînes de caractères + +Ce chemin de route correspond aux requêtes vers la route racine, `/`. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +Ce chemin de route correspond aux requêtes à `/about`. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +Ce chemin de route correspondra aux requêtes à `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Chemins de route basés sur des chaînes de caractères + + + +Les masques de chaînes de caractères dans Express 5 ne fonctionnent plus. Veuillez vous référer au guide de migration + pour plus d'informations. + + + +Ce chemin de route correspondra à `acd` et `abcd`. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +Ce chemin correspondra à `abcd`, `abbcd`, `abbbcd`, et ainsi de suite. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +Ce chemin correspondra à `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd`, et ainsi de suite. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +Ce chemin de route correspondra à `/abe` et `/abcde`. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Chemins de route basés sur des expressions régulières + +Ce chemin d'itinéraire correspondra à tout ce qui contient un "a". + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +Ce chemin d'itinéraire correspondra à `butterfly` et `dragonfly`, mais pas `butterflyman`, `dragonflyman`, et ainsi de suite. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Paramètres de la route + +Les paramètres de la route sont des segments d'URL nommés qui sont utilisés pour capturer les valeurs spécifiées à leur position dans l'URL. Les valeurs capturées sont remplies dans l'objet `req.params`, avec le nom du paramètre route spécifié dans le chemin comme leurs clés respectives. + +``` +Chemin de la route : /users/:userId/books/:bookId +URL de requête : http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +Pour définir des routes avec des paramètres d'itinéraire, il suffit de spécifier les paramètres de l'itinéraire dans le chemin de la route comme indiqué ci-dessous. + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +Le nom des paramètres de route doit être composé de "mots caractères" ([A-Za-z0-9_]). + + + +Puisque le trait d'union (`-`) et le point (`.`) sont interprétés littéralement, ils peuvent être utilisés avec des paramètres d'itinéraire à des fins utiles. + +``` +Chemin de la route : /flights/:from-:to +URL de requête : http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Chemin de la route : /plantae/:genus.:espèce +URL de requête : http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +Dans l’express 5, les caractères Regexp ne sont pas pris en charge dans les chemins de route, pour plus d’informations, veuillez +vous référer au [guide de migration](/en/guide/migrating-5#path-syntax). + + + +Pour avoir plus de contrôle sur la chaîne exacte qui peut être associée à un paramètre de route, vous pouvez ajouter une expression régulière entre parenthèses (`()`) : + +``` +Chemin de la route : /user/:userId(\d+) +URL de requête : http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Parce que l'expression régulière fait généralement partie d'une chaîne littérale, Assurez-vous d'échapper à n'importe quel caractère `\` +avec un antislash supplémentaire, par exemple `\d+`. + + + + +Dans Express 4.x, le caractère `*` dans les expressions régulières n'est pas interprété de la manière habituelle. Comme solution de contournement, utilisez `{0,}` au lieu de `*`. Cela sera probablement corrigé dans Express 5. + + +## Gestionnaires de routes + +Vous pouvez fournir plusieurs fonctions de rappel qui se comportent comme [middleware](/en/guide/using-middleware) pour traiter une requête. La seule exception est que ces callbacks peuvent appeler `next('route')` pour contourner les rappels de route restants. Vous pouvez utiliser ce mécanisme pour imposer des conditions préalables sur une route, passent ensuite le contrôle aux routes suivantes s'il n'y a pas de raison de poursuivre l'itinéraire courant. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params. d === '0') { + return next('route'); + } + res. end(`Utilisateur ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Gestionnaire spécial pour l'identifiant utilisateur 0'); +}); +``` + +Dans cet exemple : + +* `GET /user/5` → géré par la première route → envoie "Utilisateur 5" +* `GET /user/0` → première route appelle `next('route')`, passe à la prochaine route correspondant à `/user/:id` + +Les gestionnaires de routes peuvent être sous la forme d'une fonction, d'un tableau de fonctions, ou de combinaisons des deux, comme indiqué dans les exemples suivants. + +Une seule fonction de rappel peut gérer une route. Par exemple : + +```js +app.get('/example/a', (req, res) => { + res.send('Bonjour de A!'); +}); +``` + +Plus d'une fonction de rappel peut gérer une route (assurez-vous de spécifier l'objet `next`). Par exemple : + +```js +app.get( + '/example/b', + (req, res, next) => { + console. og('la réponse sera envoyée par la fonction suivante . .'); + next(); + }, + (req, res) => { + end('Bonjour de B!'); + } +); +``` + +Un tableau de fonctions de rappel peut gérer une route. Par exemple : + +```js +const cb0 = function (req, res, suivant) { + console. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +const cb2 = function (req, res) { + end('Bonjour de C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +Une combinaison de fonctions indépendantes et de tableaux de fonctions peut gérer une route. Par exemple : + +```js +const cb0 = function (req, res, suivant) { + console. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + suivante(); +}; + +app. et( + '/example/d', + [cb0, cb1], + (req, res, next) => { + console. og('la réponse sera envoyée par la fonction suivante . .'); + next(); + }, + (req, res) => { + res. end('Bonjour de D!'); + } +); +``` + +## Méthodes de réponse + +Les méthodes de l'objet de réponse (`res`) dans la table suivante peuvent envoyer une réponse au client et terminer le cycle de réponse de la requête. Si aucune de ces méthodes n'est appelée à partir d'un gestionnaire d'itinéraire, la requête du client sera suspendue. + +| Méthode | Libellé | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | Demander au téléchargement un fichier. | +| [res.end()](/en/5x/api#res.end) | Terminer le processus de réponse. | +| [res.json()](/en/5x/api#res.json) | Envoyer une réponse JSON. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Envoyer une réponse JSON avec le support JSONP. | +| [res.redirect()](/en/5x/api#res.redirect) | Rediriger une requête. | +| [res.render()](/en/5x/api#res.render) | Afficher un modèle de vue. | +| [res.send()](/en/5x/api#res.send) | Envoyer une réponse de différents types. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Envoyer un fichier en tant que flux octet. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Définit le code de statut de la réponse et envoie sa représentation en tant que corps de réponse. | + +## app.route() + +Vous pouvez créer des gestionnaires de routes chaînables pour un chemin en utilisant `app.route()`. +Parce que le chemin est spécifié à un seul endroit, la création de routes modulaires est utile, tout comme la réduction de la redondance et des fautes de frappe. Pour plus d'informations sur les routes, voir : [Documentation de Router()](/en/5x/api#router). + +Voici un exemple de gestionnaires de routes enchaînés qui sont définis en utilisant `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + end('Obtenir un livre aléatoire'); + }) + . ost((req, res) => { + res.send('Ajouter un livre'); + }) + . ut((req, res) => { + res.send('Mettre à jour le livre'); +}); +``` + +## Routeur + +Utilisez la classe `express.Router` pour créer des gestionnaires de route modulaires et montables. Une instance `Router` est un système complet de middleware et de routage ; pour cette raison, elle est souvent appelée "mini-app". + +L'exemple suivant crée un routeur en tant que module, charge une fonction middleware dedans, définit quelques routes, et monte le module routeur sur un chemin dans l'application principale. + +Créez un fichier de routeur nommé `birds.js` dans le répertoire de l'application, avec le contenu suivant : + +```js +const express = require('express'); +const router = express.Router(); + +// middleware that is specific to this router +const timeLog = (req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}; +router.use(timeLog); + +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Ensuite, chargez le module routeur dans l'application : + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', oiseaux); +``` + +L'application sera maintenant en mesure de traiter les demandes vers `/birds` et `/birds/about`, ainsi que d'appeler la fonction middleware `timeLog` qui est spécifique à la route. + +Mais si la route parente `/birds` a des paramètres de chemin, elle ne sera pas accessible par défaut à partir des sous-routes. Pour le rendre accessible, vous devrez passer l'option `mergeParams` au constructeur de routeur [reference](/en/5x/api#app.use). + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/fr/5x/guide/using-middleware.mdx b/src/content/docs/fr/5x/guide/using-middleware.mdx new file mode 100644 index 0000000000..36277e0b0c --- /dev/null +++ b/src/content/docs/fr/5x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Utilisation du middleware +description: Apprenez à utiliser les middleware dans les applications Express.js, y compris les middleware de niveau application et routeur, la gestion des erreurs et l'intégration de logiciels tiers middleware. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express est un framework web de routage et de middleware qui possède des fonctionnalités minimales : Une application Express est essentiellement une série d'appels de fonctions de middleware. + +Les fonctions *Middleware* sont des fonctions qui ont accès à l'objet [request object](/en/5x/api#req) (`req`), l'objet [réponse](/en/5x/api#res) (`res`), et la prochaine fonction du middleware dans le cycle de réponse de l'application. La prochaine fonction du middleware est généralement dénotée par une variable nommée `next`. + +Les fonctions Middleware peuvent effectuer les tâches suivantes : + +* Exécuter n'importe quel code. +* Effectuez des modifications à la requête et aux objets de réponse. +* Termine le cycle de réponse de la requête. +* Appeler la prochaine fonction du middleware dans la pile. + +Si la fonction middleware actuelle ne met pas fin au cycle de réponse de requête, elle doit appeler `next()` pour passer le contrôle à la prochaine fonction du middleware. Sinon, la demande sera laissée en suspens. + +Une application Express peut utiliser les types de middleware suivants : + +* (#middleware.application) +* [middleware au niveau du routeur] (#middleware.router) +* (#middleware.error-handling) +* (#middleware.built-in) +* [middleware de tierce partie](#middleware.third-party) + +Vous pouvez charger le middleware au niveau de l'application et du routeur avec un chemin de montage optionnel. +Vous pouvez également charger une série de fonctions middleware ensemble, ce qui crée une sous-pile du système middleware à un point de montage. + +## Outil d'interface de l'application + +Lier le middleware au niveau de l'application à une instance de l'objet [app object](/en/5x/api#app) en utilisant `app.use()` et `app. Les fonctions ETHOD()`, où `METHOD` est la méthode HTTP de la requête que la fonction middleware gère (comme GET, PUT ou POST) en minuscule. + +Cet exemple montre une fonction middleware sans chemin de montage. La fonction est exécutée chaque fois que l'application reçoit une requête. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +Cet exemple montre une fonction middleware montée sur le chemin `/user/:id`. La fonction est exécutée pour n'importe quel type de requête HTTP +sur le chemin `/user/:id`. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +Cet exemple montre une route et sa fonction de gestion (système middleware). La fonction gère les requêtes GET vers le chemin `/user/:id`. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +Voici un exemple de chargement d'une série de fonctions middleware à un point de montage, avec un chemin de montage. +Il illustre une sous-pile middleware qui affiche les informations de requête pour tout type de requête HTTP vers le chemin `/user/:id`. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + console. og('Type de requête :', req.method); + suivant(); + } +; +``` + +Les gestionnaires de routes vous permettent de définir plusieurs routes pour un chemin. L'exemple ci-dessous définit deux routes pour les requêtes GET vers le chemin `/user/:id`. La deuxième route ne posera aucun problème, mais elle ne sera jamais appelée parce que le premier parcours termine le cycle de réponse de la requête. + +Cet exemple montre une sous-pile middleware qui gère les requêtes GET vers le chemin `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req. arams.id); + next(); + }, + (req, res, next) => { + res. end('Info utilisateur'); + } +); + +// gestionnaire pour le chemin /user/:id qui affiche l'identifiant utilisateur +. et('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +Pour sauter le reste des fonctions du middleware à partir d'une pile de middleware du routeur, appelez `next('route')` pour passer le contrôle à la route suivante. + + + +`next('route')` ne fonctionnera que dans les fonctions du middleware qui ont été chargées en utilisant les fonctions +`app.METHOD()` ou `router.METHOD()`. + + + +Cet exemple montre une sous-pile middleware qui gère les requêtes GET vers le chemin `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + // si l'identifiant de l'utilisateur est 0, passer à la route + suivante si (req. arams. d === '0') next('route'); + // sinon passez le contrôle à la prochaine fonction du middleware de cette pile + else next(); + }, + (req, res, next) => { + // envoie une réponse régulière + res. end('regular'); + } +); + +// gestionnaire pour le chemin /user/:id qui envoie une réponse spéciale +. et('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +Les Middleware peuvent également être déclarés dans un tableau pour être réutilisables. + +Cet exemple montre un tableau avec une sous-pile middleware qui gère les requêtes GET vers le chemin `/user/:id` + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req. riginalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Type de requête:', req. ethod); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app. et('/user/:id', logStuff, (req, res, next) => { + res.send('User Info'); +}); +``` + +## middleware au niveau du routeur + +Le middleware au niveau du routeur fonctionne de la même manière que le middleware au niveau de l'application, sauf qu'il est lié à une instance de `express.Router()`. + +```js +routeur const = express.Router(); +``` + +Charger le middleware au niveau du routeur en utilisant les fonctions `router.use()` et `router.METHOD()`. + +L'exemple suivant réplique le système middleware qui est affiché ci-dessus pour le middleware au niveau de l'application, en utilisant le middleware au niveau du routeur: + +```js +const express = require('express'); +const app = express(); +const router = express. і(); + +// une fonction middleware sans chemin de montage. Ce code est exécuté pour chaque requête au routeur +. se(req, res, next) => { + console.log('Heure:', Date. ow()); + next(); +}); + +// une sous-pile middleware affiche les informations de requête pour tout type de requête HTTP vers le routeur /user/:id path +. se( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + . og('Type de requête:', req. ethod); + suivante(); + } +); + +// une sous-pile middleware qui gère les requêtes GET sur le routeur /user/:id path +. et( + '/user/:id', + (req, res, next) => { + // si l'identifiant de l'utilisateur est 0, passer au routeur + suivant si (req. arams. d === '0') next('route'); + // passe autrement le contrôle à la prochaine fonction du middleware de cette pile + else next(); + }, + (req, res, next) => { + // renvoie une page normale + res. ender('regular'); + } +); + +// gestionnaire pour le chemin /user/:id qui affiche une page spéciale +. et('/user/:id', (req, res, next) => { + . og(req.params.id); + res.render('special'); +}); + +// monte le routeur sur l'application +app.use('/', router); +``` + +Pour sauter le reste des fonctions du middleware du routeur, appelez `next('router')` +pour passer le contrôle hors de l'instance du routeur. + +Cet exemple montre une sous-pile middleware qui gère les requêtes GET vers le chemin `/user/:id`. + +```js +const express = require('express'); +const app = express(); +const router = express. і(); + +// prédice le routeur avec un contrôle et un renflouement si nécessaire le routeur +. se(req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +routeur. et('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// utilise le routeur et 401 tout ce qui passe par l'application +. se('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## Gestion des erreurs du middleware + + + +La gestion d'erreurs du middleware prend toujours *four* arguments. Vous devez fournir quatre arguments à +l'identifier comme une fonction de gestion des erreurs du middleware. Même si vous n'avez pas besoin d'utiliser l'objet `next` +, vous devez le spécifier pour maintenir la signature. Sinon, l'objet `next` sera +interprété comme un middleware normal et ne gérera pas les erreurs. + + + +Définissez les fonctions du middleware de la même manière que les autres fonctions du middleware, sauf avec quatre arguments au lieu de trois, spécifiquement avec la signature `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Quelque chose s'est cassé !'); +}); +``` + +Pour plus de détails sur la gestion des erreurs du middleware, voir : [Gestion des erreurs](/en/guide/error-handling). + +## middleware intégré + +À partir de la version 4.x, Express ne dépend plus de [Connect](https://github.com/senchalabs/connect). Les fonctions du middleware +qui étaient précédemment incluses avec Express sont maintenant dans des modules séparés ; voir [la liste des fonctions du middleware] (https://github.com/senchalabs/connect#middleware). + +Express a les fonctions internes suivantes : + +* [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. +* [express.json](/en/5x/api#express.json) analyse les requêtes entrantes avec des charges utiles JSON. **NOTE : Disponible avec Express 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) analyse les requêtes entrantes avec des charges utiles encodées en URL. **NOTE : Disponible avec Express 4.16.0+** + +## middleware de tierce partie + +Utilisez des logiciels tiers pour ajouter des fonctionnalités aux applications Express. + +Installez le module Node.js pour la fonctionnalité requise, puis chargez-le dans votre application au niveau de l'application ou au niveau du routeur. + +L'exemple suivant illustre l'installation et le chargement de la fonction middleware d'analyse de cookies `cookie-parser`. + +```bash +$ npm install cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// charge le middleware +app.use(cookieParser()); +``` + +Pour une liste partielle des fonctions middleware tierces qui sont couramment utilisées avec Express, voir : [middleware de tierce] (../resources/middleware). diff --git a/src/content/docs/fr/5x/guide/using-template-engines.mdx b/src/content/docs/fr/5x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..581a2b0cca --- /dev/null +++ b/src/content/docs/fr/5x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Utiliser les moteurs de gabarits avec Express +description: Découvrez comment intégrer et utiliser des moteurs de gabarits tels que Pug, Handlebars et EJS avec Express.js pour rendre les pages HTML dynamiques efficacement. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Un *moteur de modèle* vous permet d'utiliser des fichiers de modèles statiques dans votre application. Lors de l'exécution, le moteur de gabarit remplace les variables +dans un fichier de gabarit par des valeurs réelles, et transforme le modèle en un fichier HTML envoyé au client. +Cette approche facilite la conception d'une page HTML. + +Le [générateur d'application Express](/en/starter/generator) utilise [Pug](https://pugjs.org/api/getting-started.html) par défaut, mais il supporte aussi [Handlebars](https://www.npmjs.com/package/handlebars), et [EJS](https://www.npmjs.com/package/ejs), entre autres. + +Pour afficher les fichiers de gabarit, définissez les [propriétés de réglage de l'application](/en/4x/api#app.set), dans le `app.js` par défaut créé par le générateur: + +* `views`, le répertoire où se trouvent les fichiers de modèle. Ex. : `app.set('vues', './views')`. + Par défaut, le répertoire `views` se trouve à la racine de l'application. +* `voir le moteur`, le moteur de gabarit à utiliser. Par exemple, pour utiliser le moteur de gabarit Pug : `app.set('moteur de vue', 'pug')`. + +Ensuite, installez le paquet npm correspondant au moteur de gabarits ; par exemple pour installer Pug: + +```bash +$ npm install pug --save +``` + + +Les moteurs de gabarits conformes à la norme Express tels que Pug exportent une fonction nommée `__express(filePath, options, callback)`, +qui `res.render()` appelle pour rendre le code du gabarit. + +Certains moteurs de gabarits ne suivent pas cette convention. La bibliothèque [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +suit cette convention en mappant tous les moteurs de gabarits populaires Node.js, et fonctionne donc parfaitement dans Express. + + + +Une fois que le moteur de vue est défini, vous n'avez pas à spécifier le moteur ou charger le module moteur de gabarit dans votre application ; +Express charge le module en interne, par exemple : + +```js +app.set('moteur d'affichage', 'pug'); +``` + +Ensuite, créez un fichier de modèle Pug nommé `index.pug` dans le dossier `views`, avec le contenu suivant: + +```pug +html + devant + title= titre + corps + h1= message +``` + +Créez une route pour afficher le fichier `index.pug`. Si la propriété `view engine` n'est pas définie, +vous devez spécifier l'extension du fichier `view`. Sinon, vous pouvez l'oublier. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Bonjour !' }); +}); +``` + +Lorsque vous faites une requête sur la page d'accueil, le fichier `index.pug` sera rendu en HTML. + +Le cache du moteur de vue ne cache pas le contenu de la sortie du modèle, seulement le modèle sous-jacent. La vue est toujours rendue à chaque requête, même lorsque le cache est activé. diff --git a/src/content/docs/fr/5x/guide/writing-middleware.mdx b/src/content/docs/fr/5x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..4f2f2062a1 --- /dev/null +++ b/src/content/docs/fr/5x/guide/writing-middleware.mdx @@ -0,0 +1,209 @@ +--- +title: Écriture de middleware pour utilisation dans les applications Express +description: Apprenez à écrire des fonctions personnalisées de middleware pour les applications Express.js, y compris des exemples et des pratiques exemplaires pour améliorer la gestion des requêtes et des réponses. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Les fonctions *Middleware* sont des fonctions qui ont accès à l'objet [request object](/en/5x/api#req) (`req`), l'objet [réponse](/en/5x/api#res) (`res`), et la fonction `next` dans le cycle de réponse de l'application. La fonction `next` est une fonction dans le routeur Express qui, lorsqu'elle est appelée, exécute le middleware qui succède au middleware actuel. + +Les fonctions Middleware peuvent effectuer les tâches suivantes : + +* Exécuter n'importe quel code. +* Effectuez des modifications à la requête et aux objets de réponse. +* Termine le cycle de réponse de la requête. +* Appelez le prochain middleware dans la pile. + +Si la fonction middleware actuelle ne met pas fin au cycle de réponse de requête, elle doit appeler `next()` pour passer le contrôle à la prochaine fonction du middleware. Sinon, la demande sera laissée en suspens. + +La figure suivante montre les éléments d'un appel de fonction middleware : + +![Elements of a middleware function call](/images/express-mw.png) + +À partir de Express 5, les fonctions middleware qui retournent une Promise appelleront `next(value)` quand elles rejettent ou lancent une erreur. `next` sera appelé avec la valeur rejetée ou avec l'erreur levée. + +## Exemple + +Voici un exemple de simple application "Hello World" Express. +Le reste de cet article va définir et ajouter trois fonctions middleware à l'application : +un appelé `myLogger` qui affiche un message de log simple. on appelle `requestTime` que +affiche l'horodatage de la requête HTTP, et un appelé `validateCookies` qui valide les cookies entrants. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +### Fonction Middleware myLogger + +Voici un exemple simple d'une fonction middleware appelée "myLogger". Cette fonction affiche seulement +"LOGGED" lorsqu'une requête vers l'application passe à travers elle. La fonction middleware est assignée à une variable +nommée `myLogger`. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +Notez l'appel ci-dessus à `next()`. Appeler cette fonction appelle la prochaine fonction du middleware dans +l'application. La fonction `next()` n'est pas une partie du noeud. s ou API Express, mais est le troisième argument +qui est passé à la fonction middleware. La fonction `next()` pourrait être nommée quoi que ce soit, +mais par convention elle est toujours nommée "next". Pour éviter toute confusion, utilisez toujours cette convention. + + + +Pour charger la fonction middleware, appelez `app.use()`, en spécifiant la fonction middleware. +Par exemple, le code suivant charge la fonction middleware `myLogger` avant la route vers le chemin racine (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console. og('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +Chaque fois que l'application reçoit une demande, elle affiche le message "LOGGGED" vers le terminal. + +L'ordre de chargement du middleware est important : les fonctions du middleware qui sont chargées en premier sont également exécutées en premier. + +Si `myLogger` est chargé après la route vers le chemin racine, la requête ne l'atteint jamais et l'application n'affiche pas "LOGGED", parce que le gestionnaire de route du chemin racine termine le cycle de réponse de requête. + +La fonction du middleware `myLogger` affiche simplement un message, passe ensuite la requête à la prochaine fonction middleware de la pile en appelant la fonction `next()`. + +### Middleware fonction requestTime + +Ensuite, nous allons créer une fonction middleware appelée "requestTime" et ajouter une propriété appelée `requestTime` +à l'objet requête. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +L'application utilise maintenant la fonction middleware `requestTime`. Aussi, la fonction callback de la route du chemin racine utilise la propriété que la fonction middleware ajoute à `req` (l'objet de requête). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req. equestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app. et('/', (req, res) => { + let responseText = 'Bonjour le monde!
'; + responseText += `Demandé à: ${req.requestTime}`; + res. end(responseText); +}); + +app.listen(3000); +``` + +Lorsque vous faites une demande à la racine de l'application, l'application affiche maintenant l'horodatage de votre requête dans le navigateur. + +### format@@0 Middleware function validateCookies + +Enfin, nous allons créer une fonction middleware qui valide les cookies entrants et envoie une réponse 400 si les cookies sont invalides. + +Voici un exemple de fonction qui valide les cookies avec un service asynchrone externe. + +```js +fonction async cookieValidator(cookies) { + essayer { + attendre externalyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Cookies invalides'); + } +} +``` + +Ici, nous utilisons le middleware [`cookie-parser`](/en/resources/middleware/cookie-parser) pour analyser les cookies entrants de l'objet `req` et les passer à notre fonction `cookieValidator`. Le middleware `validateCookies` retourne une Promesse que si le rejet déclenchera automatiquement notre gestionnaire d'erreurs. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('. cookieValidator'); + +const app = express(); + +fonction async validateCookies(req, res, next) { + attendent cookieValidator(req. ookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// gestionnaire d'erreur +app. se(err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Notez comment `next()` est appelé après `wait cookieValidator(req.cookies)`. Cela garantit que si +`cookieValidator` résoud, le prochain middleware de la pile sera appelé. Si vous passez quelque chose +à la fonction `next()` (sauf la chaîne `'route'` ou `'router'`), Express considère que la requête +actuelle est une erreur et ignorera toute fonction de routage et de middleware +qui ne gère pas les autres fonctions de routage. + + + +Parce que vous avez accès à l'objet requête, à l'objet de réponse, à la prochaine fonction du middleware dans la pile, et à l'ensemble du nœud. s API, les possibilités avec les fonctions du middleware sont infinies. + +Pour plus d'informations sur le middleware Express, voir : [Utiliser un middleware Express](/en/guide/using-middleware). + +## Logiciel middleware configurable + +Si vous avez besoin que votre middleware soit configurable, exportez une fonction qui accepte un objet d'options ou d'autres paramètres, qui retourne ensuite l'implémentation du middleware en fonction des paramètres d'entrée. + +Fichier: `my-middleware.js` + +```js +module. xports = function (options) { + fonction de retour (req, res, next) { + // Implémente la fonction middleware basée sur l'objet d'options + next(); + }; +}; +``` + +Le middleware peut maintenant être utilisé comme montré ci-dessous. + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Reportez-vous à [cookie-session](https://github.com/expressjs/cookie-session) et [compression](https://github.com/expressjs/compression) pour des exemples de middleware configurables. diff --git a/src/content/docs/fr/5x/starter/basic-routing.mdx b/src/content/docs/fr/5x/starter/basic-routing.mdx new file mode 100644 index 0000000000..1259c9d112 --- /dev/null +++ b/src/content/docs/fr/5x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Routage de base +description: Apprenez les fondamentaux du routage dans les applications Express.js, y compris comment définir des routes, gérer des méthodes HTTP et créer des gestionnaires de routes pour votre serveur web. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* désigne la façon dont une application répond à une requête client à un point de terminaison particulier, qui est une URI (ou un chemin) et une méthode spécifique de requête HTTP (GET, POST, etc.). + +Chaque route peut avoir une ou plusieurs fonctions de gestionnaire, qui sont exécutées lorsque la route est correspondante. + +La définition de la route prend la structure suivante : + +```js +app.METHOD(PATH, HANDLER); +``` + +Où : + +* `app` est une instance de `express`. +* `METHOD` est une [méthode de requête HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), en minuscule. +* `PATH` est un chemin sur le serveur. +* `HANDLER` est la fonction exécutée lorsque la route est correspondante. + + + +This tutorial assumes that an instance of `express` named `app` is created and the server is +running. Si vous n'êtes pas familier avec la création d'une application et son démarrage, consultez l'exemple Bonjour le monde +. + + + +Les exemples suivants illustrent la définition de routes simples. + +Répondez avec `Hello World!` sur la page d'accueil: + +```js +app.get('/', (req, res) => { + res.send('Hello World!'); +}); +``` + +Répondre à une requête POST sur la route racine (`/`), la page d'accueil de l'application : + +```js +app.post('/', (req, res) => { + res.send('Requête POST'); +}); +``` + +Répondre à une requête PUT sur la route `/user`: + +```js +app.put('/user', (req, res) => { + res.send('Requête PUT à /user'); +}); +``` + +Répondre à une requête DELETE sur la route `/user`: + +```js +app.delete('/user', (req, res) => { + res.send('Requête DELETE à /user'); +}); +``` + +Pour plus de détails sur le routage, consultez le [guide de routage] (/en/guide/routing). diff --git a/src/content/docs/fr/5x/starter/examples.mdx b/src/content/docs/fr/5x/starter/examples.mdx new file mode 100644 index 0000000000..674e561a00 --- /dev/null +++ b/src/content/docs/fr/5x/starter/examples.mdx @@ -0,0 +1,49 @@ +--- +title: Exemples Express +description: Explorez une collection d'exemples d'applications Express.js couvrant divers cas d'utilisation, intégrations et configurations avancées pour vous aider à apprendre et à construire vos projets. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Cette page contient la liste des exemples utilisant Express. + +* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Authentification avec login et mot de passe +* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - négociation de contenu HTTP +* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Working with cookie-based sessions +* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Working with cookies +* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transfert de fichiers vers le client +* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Travailler avec un modèle JavaScript embarqué (ejs) +* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Création des pages d'erreur +* [error](https://github.com/expressjs/express/tree/master/examples/error) - Travailler avec un middleware d'erreur +* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Gestionnaire de requêtes simple +* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown comme moteur de gabarit +* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Travailler avec plusieurs routeurs Express +* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - Contrôleurs de style MVC +* [online](https://github.com/expressjs/express/tree/master/examples/online) - Suivi de l'activité de l'utilisateur en ligne avec les paquets `online` et `redis` +* [params](https://github.com/expressjs/express/tree/master/examples/params) - Travailler avec les paramètres de la route +* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Opérations HTTP multiples sur la même ressource +* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organiser des routes à l'aide d'une carte +* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Travailler avec le middleware de route +* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organiser des routes par ressource +* [search](https://github.com/expressjs/express/tree/master/examples/search) - Search API +* [session](https://github.com/expressjs/express/tree/master/examples/session) - Sessions utilisateur +* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Servir des fichiers statiques +* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Working with virtual hosts +* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Rendu dynamique des vues +* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Enregistrement des données dans l'objet de requête entre les appels de middleware +* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Service API simple + +## Exemples supplémentaires + +Ce sont quelques exemples supplémentaires avec des intégrations plus étendues. + + + +Cette information se réfère à des sites tiers, des produits ou des modules tiers qui ne sont pas maintenus par l'équipe +Expressjs. La liste ci-dessous ne constitue pas une approbation ou une recommandation de l'équipe du projet +Expressjs. + + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Application Fullstack avec Express et Next.js en utilisant [Prisma](https://www.npmjs.com/package/prisma) en tant qu'ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API avec Express in TypeScript en utilisant [Prisma](https://www.npmjs.com/package/prisma) en tant qu'ORM diff --git a/src/content/docs/fr/5x/starter/faq.md b/src/content/docs/fr/5x/starter/faq.md new file mode 100644 index 0000000000..494c74698b --- /dev/null +++ b/src/content/docs/fr/5x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: Foire Aux Questions +description: Retrouvez les réponses aux questions les plus fréquemment posées sur Express.js, y compris les sujets sur la structure de l'application, les modèles, l'authentification, les moteurs de gabarit, la gestion des erreurs, et plus encore. +--- + +## Comment structurer ma candidature ? + +Il n'y a pas de réponse définitive à cette question. La réponse dépend +de l'échelle de votre candidature et de l'équipe impliquée. To be as +flexible as possible, Express makes no assumptions in terms of structure. + +Les routes et autres logiques spécifiques à une application peuvent vivre dans autant de fichiers +que vous le souhaitez, dans n'importe quelle structure de répertoire que vous préférez. View the following +examples for inspiration: + +- [Liste des itinéraires](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Route map](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Il y a également des extensions tierces pour Express, qui simplifient certains de ces modèles: + +- [Itinéraire de ressource](https://github.com/expressjs/express-resource) + +## Comment définir des modèles? + +Express n'a aucune notion de base de données. This concept is +left up to third-party Node modules, allowing you to +interface with nearly any database. + +Voir [LoopBack](http://loopback.io) pour un framework basé sur Express, centré autour de modèles. + +## Comment puis-je authentifier les utilisateurs ? + +Authentication is another opinionated area that Express does not +venture into. Vous pouvez utiliser n'importe quel schéma d'authentification que vous souhaitez. +Pour un simple nom d'utilisateur / schéma de mot de passe, voir [cet exemple](https://github.com/expressjs/express/tree/master/examples/auth). + +## Quels moteurs de gabarits sont supportés par Express ? + +Express prend en charge tout moteur de gabarit qui est conforme à la signature `(path, locals, callback)`. +Pour normaliser les interfaces du moteur de gabarits et la mise en cache, consultez le projet +[consolidate.js](https://github.com/visionmedia/consolidate.js) +pour plus de support. Les moteurs de gabarits non listés peuvent toujours supporter la signature Express. + +Pour plus d'informations, voir [Utilisation de moteurs de gabarits avec Express](/en/guide/using-template-engines). + +## Comment gérer 404 réponses? + +Dans Express, 404 réponses ne sont pas le résultat d'une erreur, donc +le middleware de gestion d'erreurs ne les capturera pas. Ce comportement est +car une réponse 404 indique simplement l'absence de travail supplémentaire à faire ; +en d'autres termes, Express a exécuté toutes les fonctions et routes du middleware, +et a trouvé qu'aucun d'eux n'a répondu. All you need to +do is add a middleware function at the very bottom of the stack (below all other functions) +to handle a 404 response: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Ajoute des routes dynamiquement à l'exécution sur une instance de `express.Router()` +afin que les routes ne soient pas remplacées par une fonction de middleware. + +## Comment configurer un gestionnaire d'erreur ? + +Vous définissez le middleware de la même manière que les autres middleware, +sauf avec quatre arguments au lieu de trois; spécifiquement avec la signature `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Pour plus d'informations, voir [Gestion des erreurs] (/en/guide/error-handling). + +## Comment rendre le HTML simple ? + +Vous ne le faites pas! Il n'y a pas besoin de "render" HTML avec la fonction `res.render()`. +Si vous avez un fichier spécifique, utilisez la fonction `res.sendFile()`. +Si vous utilisez beaucoup d'actifs depuis un répertoire, utilisez la fonction `express.static()` +middleware. + +## Quelle version de Node.js est requise ? + +- [Express 4.x](/en/4x/api) nécessite Node.js 0.10 ou supérieur. +- [Express 5.x](/en/5x/api) nécessite Node.js 18 ou plus. diff --git a/src/content/docs/fr/5x/starter/generator.mdx b/src/content/docs/fr/5x/starter/generator.mdx new file mode 100644 index 0000000000..fdfd9b4883 --- /dev/null +++ b/src/content/docs/fr/5x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Générateur d'application Express +description: Apprenez à utiliser l'outil de générateur d'applications Express pour créer rapidement un squelette pour vos applications Express.js, en rationalisant la configuration et la configuration. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Utilisez l'outil de générateur d'applications, `express-generator`, pour créer rapidement un squelette d'application. + +Vous pouvez exécuter le générateur d'application avec la commande `npx` (disponible dans Node.js 8.2.0). + +```bash +Générateur de npx express $ +``` + +Pour les versions antérieures de Node, installez le générateur d'application en tant que paquet npm global puis lancez le : + +```bash +$ npm install -g express-generator +$ express +``` + +Affiche les options de la commande avec l'option `-h`: + +```bash +$ express -h + + Utilisation : express [options] [dir] + + Options : + + -h, --help affiche les informations d'utilisation + --version affiche le numéro de version + -e, --ejs add ejs engine support + --hbs add handlebar engine support + --pug add pug engine support + -H, --hogan add hogan. le support du moteur + --no-view générer sans afficher le moteur + -v, --view ajouter la vue support (ejs|hbs|hjs|jade|pug|twig|vash) (par défaut jade) + -c, --css ajoute la feuille de style support (moins|stylus|compass|sass) (par défaut, css simple) + --git add . itignore + -f, --force sur un répertoire non vide +``` + +Par exemple, ce qui suit crée une application Express nommée *myapp*. L'application sera créée dans un dossier nommé *myapp* dans le répertoire de travail actuel et le moteur de vue sera réglé sur Pug: + +```bash +$ express --view=pug myapp + + create : myapp + create : myapp/package.json + create : myapp/app. s + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index. s + créer : monapp/routes/utilisateurs. s + créer : myapp/public/stylesheets + create : myapp/public/stylesheets/style. ss + create : myapp/views + create : myapp/views/index. ug + create : myapp/views/layout.pug + create : myapp/views/error. ug + create : monapp/bin + create : myapp/bin/www +``` + +Installez ensuite les dépendances : + +```bash +$ cd myapp +$ npm install +``` + +Sous MacOS ou Linux, exécutez l'application avec cette commande : + +```bash +$ DEBUG=myapp:* npm start +``` + +Sous l'invite de commande Windows, utilisez cette commande : + +```bash +> set DEBUG=myapp:* & npm start +``` + +Sous Windows PowerShell, utilisez cette commande : + +```bash +PS> $env:DEBUG='myapp:*'; npm start +``` + +Ensuite, chargez `http://localhost:3000/` dans votre navigateur pour accéder à l'application. + +L'application générée a la structure de répertoire suivante : + +```bash +. +── app.js +── bin +文 ─ www +── package. fils +── public +Ω─ images +Ω─ javascripts +文 ── feuilles de style +Ω ─ style. ss +── routes +文── index.js +Ω ── utilisateurs. s + ── vues + ── erreur. ug + ── index.pug + ─ layout.pug + +7 répertoires, 9 fichiers +``` + + + +La structure d'application créée par le générateur n'est qu'un des nombreux moyens de structurer les applications Express. +N'hésitez pas à utiliser cette structure ou à la modifier pour mieux répondre à vos besoins. + + diff --git a/src/content/docs/fr/5x/starter/hello-world.mdx b/src/content/docs/fr/5x/starter/hello-world.mdx new file mode 100644 index 0000000000..8e38e29de6 --- /dev/null +++ b/src/content/docs/fr/5x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Bonjour l'exemple du monde +description: Commencez avec Express.js en construisant une simple application 'Hello World', en démontrant la configuration de base et la création de serveurs pour les débutants. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Intégré ci-dessous est essentiellement l'application Express la plus simple que vous puissiez créer. C'est une seule application de fichier +— *pas* ce que vous obtiendrez si vous utilisez le [générateur Express](/en/starter/generator), que +crée l'échafaudage pour une application complète avec de nombreux fichiers JavaScript, des modèles Jade, et des sous-répertoires +à diverses fins. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res. end('Hello World!'); +}); + +app.listen(port, () => { + console.log(`Exemple d'application d'écoute sur le port ${port}`); +}); +``` + +Cette application démarre un serveur et écoute le port 3000 pour les connexions. L'application répond avec "Hello World!" pour les demandes +à l'URL racine (`/`) ou *route*. Pour tous les autres chemins, il répondra avec un **404 Not Found**. + +## Exécution locale + +Créez d'abord un répertoire nommé `myapp`, changez et exécutez `npm init`. Ensuite, installez `express` en tant que dépendance, conformément au [guide d'installation](/en/starter/installing). + +Dans le dossier `myapp`, créez un fichier nommé `app.js` et copiez le code à partir de l'exemple ci-dessus. + + + +Les `req` (request) et `res` (response) sont les mêmes objets que le noeud fournit, donc vous pouvez +appeler `req. ipe()`, `req.on('data', callback)`, et tout autre chose que vous feriez sans Express +impliqué. + + + +Exécutez l'application avec la commande suivante : + +```bash +$ node app.js +``` + +Ensuite, chargez `http://localhost:3000/` dans un navigateur pour voir la sortie. diff --git a/src/content/docs/fr/5x/starter/installing.mdx b/src/content/docs/fr/5x/starter/installing.mdx new file mode 100644 index 0000000000..6305971087 --- /dev/null +++ b/src/content/docs/fr/5x/starter/installing.mdx @@ -0,0 +1,41 @@ +--- +title: Installation en cours +description: Apprenez à installer Express.js dans votre environnement Node.js, y compris la configuration de votre répertoire de projet et la gestion des dépendances avec npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Avant de commencer, assurez-vous que vous avez [Node.js](https://nodejs.org/) 18 ou supérieur installé. Ensuite, créez un répertoire pour votre application et naviguez dedans. + +```bash +mkdir myapp +cd myapp +``` + +Utilisez la commande `npm init` pour créer un fichier `package.json` pour votre application. +Pour plus d'informations sur le fonctionnement de `package.json`, voir [Specifics of npm's package.json handling](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +Cette commande vous invite à trouver un certain nombre de choses, telles que le nom et la version de votre application. +Pour l'instant, vous pouvez simplement appuyer sur RETURN pour accepter les valeurs par défaut pour la plupart d'entre eux, à l'exception de la règle suivante : + +``` +point d'entrée: (index.js) +``` + +Entrez `app.js`, ou quel que soit le nom du fichier principal. Si vous voulez qu'il soit `index.js`, appuyez sur RETURN pour accepter le nom de fichier par défaut suggéré. + +Maintenant, installez Express dans le répertoire `myapp` et sauvegardez-le dans la liste des dépendances. Par exemple : + +```bash +npm installation express +``` + +Pour installer Express temporairement et ne pas l'ajouter à la liste des dépendances : + +```bash +npm install express --no-save +``` diff --git a/src/content/docs/fr/5x/starter/static-files.mdx b/src/content/docs/fr/5x/starter/static-files.mdx new file mode 100644 index 0000000000..041757b116 --- /dev/null +++ b/src/content/docs/fr/5x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Servir les fichiers statiques dans Express +description: Comprendre comment servir les fichiers statiques comme les images, CSS, et JavaScript dans les applications Express.js en utilisant le middleware 'statique' intégré. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Pour servir des fichiers statiques tels que des images, des fichiers CSS et des fichiers JavaScript, utilisez la fonction middleware intégrée `express.static` dans Express. + +La signature de la fonction est : + +```js +express.static(root, [options]); +``` + +L'argument `root` spécifie le répertoire racine à partir duquel servir les actifs statiques. +Pour plus d'informations sur l'argument `options`, voir [express.static](/en/5x/api#express.static). + +Par exemple, utilisez le code suivant pour servir les images, les fichiers CSS et JavaScript dans un répertoire nommé `public`: + +```js +app.use(express.static('public')); +``` + +Maintenant, vous pouvez charger les fichiers qui se trouvent dans le répertoire `public`: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express recherche les fichiers relatifs au répertoire statique, donc le nom du répertoire statique +ne fait pas partie de l'URL. + + + +Pour utiliser plusieurs répertoires statiques, appelez la fonction middleware `express.static` plusieurs fois : + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express recherche les fichiers dans l'ordre dans lequel vous définissez les répertoires statiques avec la fonction `express.static`. + + + +Pour de meilleurs résultats, utilisez un proxy +inversé pour améliorer les performances de +servant des actifs statiques. + + + +Pour créer un préfixe de chemin virtuel (où le chemin n'existe pas dans le système de fichiers) pour les fichiers qui sont servis par le fichier `express. fonction tatic`, [spécifiez un chemin de montage](/en/5x/api#app.use) pour le répertoire statique, comme indiqué ci-dessous: + +```js +app.use('/static', express.static('public')); +``` + +Maintenant, vous pouvez charger les fichiers qui se trouvent dans le dossier `public` à partir du préfixe de chemin `/static`. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +Cependant, le chemin que vous fournissez à la fonction `express.static` est relatif au répertoire depuis lequel vous lancez votre processus `node`. Si vous exécutez l'application express à partir d'un autre répertoire, il est plus sûr d'utiliser le chemin absolu du répertoire que vous voulez servir: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public'))); +``` + +Pour plus de détails sur la fonction `serve-static` et ses options, voir [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/it/4x/advanced/developing-template-engines.md b/src/content/docs/it/4x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..3c00548d60 --- /dev/null +++ b/src/content/docs/it/4x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Sviluppo di modelli di motori per Express +description: Impara a sviluppare motori di template personalizzati per Express.js utilizzando app.engine(), con esempi sulla creazione e l'integrazione della tua logica di rendering dei modelli. +--- + +Usa il metodo `app.engine(ext, callback)` per creare il tuo modello di motore. `ext` si riferisce all'estensione del file, e `callback` è la funzione del motore del modello, che accetta i seguenti elementi come parametri: la posizione del file, l'oggetto opzioni, e la funzione di callback. + +Il seguente codice è un esempio di implementazione di un semplice modello di motore per il rendering dei file `.ntl`. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +La tua app sarà ora in grado di visualizzare i file `.ntl`. Crea un file chiamato `index.ntl` nella directory `views` con il seguente contenuto. + +```pug +#title# +#message# +``` + +Quindi, crea il seguente percorso nella tua app. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +Quando fai una richiesta alla home page, `index.ntl` sarà renderizzato come HTML. diff --git a/src/content/docs/it/4x/guide/behind-proxies.mdx b/src/content/docs/it/4x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..eeb3cb8160 --- /dev/null +++ b/src/content/docs/it/4x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Espresso dietro i proxy +description: Scopri come configurare le applicazioni Express.js per funzionare correttamente dietro i proxy inversi, anche utilizzando l'impostazione del proxy di trust per gestire gli indirizzi IP del client. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Quando si esegue un'app Express dietro un proxy inverso, alcune delle API Express possono restituire valori diversi da quelli previsti. Al fine di adeguarsi a questo, l'impostazione dell'applicazione `trust proxy` può essere utilizzata per esporre le informazioni fornite dal proxy inverso nelle API Express. Il problema più comune è l'espressione API che espone l'indirizzo IP del cliente può invece mostrare un indirizzo IP interno del proxy inverso. + + + +Durante la configurazione dell'impostazione `trust proxy`, è importante capire l'esatta configurazione del proxy inverso +. Dal momento che questa impostazione sarà i valori di fiducia forniti nella richiesta, è importante che +la combinazione dell'impostazione in Express corrisponda al funzionamento del proxy inverso. + + + +L'impostazione dell'applicazione `trust proxy` può essere impostata su uno dei valori elencati nella seguente tabella. + + + + + + + + + + + + + + + + + + Funzione + + +
TypeValue
Boolean +Se `true`, l'indirizzo IP del cliente è inteso come la voce più sinistra nell'intestazione `X-Forwarded-For`. + +Se `false`, l'app è intesa come rivolta direttamente al client e l'indirizzo IP del cliente è derivato da `req.socket.remoteAddress`. Questa è l'impostazione predefinita. + + +Quando si imposta a `true`, è importante assicurarsi che l'ultimo proxy inverso attendibile stia rimuovendo/sovrascrivendo tutte le seguenti intestazioni HTTP: `X-Forwarded-For`, `X-Forwarded-Host`, e `X-Forwarded-Proto`, altrimenti potrebbe essere possibile per il cliente fornire qualsiasi valore. + +
indirizzi IP +Un indirizzo IP, una sottorete, o un array di indirizzi IP e sottoreti a cui fidarsi come proxy inverso. Il seguente elenco mostra i nomi pre-configurati delle sottorete + +* loopback - `127.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +È possibile impostare gli indirizzi IP in uno dei seguenti modi: + +```js +app.set('trust proxy', 'loopback'); // specify a single subnet +app.set('trust proxy', 'loopback, 123.123.123.123'); // specify a subnet and an address +app.set('trust proxy', 'loopback, linklocal, uniquelocal'); // specify multiple subnets as CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // specify multiple subnets as an array +``` + +Se specificato, gli indirizzi IP o le sottoreti sono esclusi dal processo di determinazione dell'indirizzo, e l'indirizzo IP non attendibile più vicino al server dell'applicazione è determinato come indirizzo IP del client. Questo funziona controllando se `req.socket.remoteAddress` è attendibile. In tal caso, ogni indirizzo in `X-Forwarded-For` viene controllato da destra a sinistra fino al primo indirizzo non fidato. + +
Numero +Usa l'indirizzo che è al massimo `n` numero di luppolo lontano dall'applicazione Express. `req.socket.remoteAddress` è il primo hop, e il resto sono cercati nell'intestazione `X-Forwarded-For` da destra a sinistra. Un valore di `0` significa che il primo indirizzo non attendibile sarebbe `req.socket.remoteAddress`, cioè non c'è un proxy inverso. + + +Quando si utilizza questa impostazione, è importante assicurarsi che non ci siano multipli, percorsi diversi per l'applicazione Express in modo che il client possa essere inferiore al numero configurato di luppolo di distanza, altrimenti potrebbe essere possibile per il cliente fornire qualsiasi valore. + +
+ +Implementazione fiducia personalizzata. + +```js +app.set('trust proxy', (ip) => { + if (ip === '127.0.0.1' ip === '123.123.123. 23') + return true; // trusted IPs + else return false; +}); +``` + +
+ +Abilitare il `trust proxy` avrà il seguente impatto: + +
    +
  • + Il valore di [req.hostname](/en/api#req.hostname) è derivato dal valore impostato nell'intestazione + `X-Forwarded-Host`, che può essere impostato dal cliente o dal proxy. +
    • +
  • + `X-Forwarded-Proto` può essere impostato dal proxy inverso per dire all'app se si tratta di `↓ ` o + `http` o anche di un nome non valido. Questo valore è riflesso da [req.protocol](/en/api#req.protocol). +
    • +
  • + I valori [req.ip](/en/api#req.ip) e [req.ips](/en/api#req.ips) sono popolati in base all'indirizzo del socket + e all'intestazione `X-Forwarded-For`, a partire dal primo indirizzo non fidato. +
    • +
+ +L'impostazione `trust proxy` è implementata usando il pacchetto [proxy-addr](https://www.npmjs.com/package/proxy-addr). Per ulteriori informazioni, consultare la documentazione. diff --git a/src/content/docs/it/4x/guide/debugging.mdx b/src/content/docs/it/4x/guide/debugging.mdx new file mode 100644 index 0000000000..592e46618a --- /dev/null +++ b/src/content/docs/it/4x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Debug Express +description: Scopri come abilitare e utilizzare i log di debug nelle applicazioni Express.js impostando la variabile di ambiente DEBUG per la risoluzione dei problemi migliorata. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Per vedere tutti i log interni utilizzati in Express, imposta la variabile d'ambiente `DEBUG` su +`express:*` quando lancia la tua app. + +```bash +$ DEBUG=express:* node index.js +``` + +Su Windows, utilizzare il comando corrispondente. + +```bash +> $env:DEBUG = "express:*"; node index.js +``` + +L'esecuzione di questo comando nell'app predefinita generata dal [express generator](/en/starter/generator) stampa il seguente output: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +Quando viene fatta una richiesta all'applicazione, vedrete i registri specificati nel codice Express: + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index.pug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +Per vedere i log solo dall'implementazione del router, imposta il valore di `DEBUG` su `express:router`. Allo stesso modo, per vedere i log solo dall'implementazione dell'applicazione, imposta il valore di `DEBUG` su `express:application`, e così via. + +## Applicazioni generate da `express` + +Un'applicazione generata dal comando `express` utilizza il modulo `debug` e il suo namespace di debug è indirizzato al nome dell'applicazione. + +Ad esempio, se hai generato l'app con `$ express sample-app`, puoi abilitare le istruzioni di debug con il seguente comando: + +```bash +$ DEBUG=sample-app:* node ./bin/www +``` + +È possibile specificare più di uno spazio dei nomi di debug assegnando una lista di nomi separati da virgole: + +```bash +$ DEBUG=http,mail,express:* node index.js +``` + +## Opzioni avanzate + +Quando si esegue attraverso Node.js, è possibile impostare alcune variabili di ambiente che cambieranno il comportamento della registrazione di debug: + +| Nome | Scopo | +| ------------------- | ------------------------------------------------------- | +| `DEBUG` | Abilita/disabilita spazi di debug specifici. | +| `DEBUG_COLORS` | Indica se usare o meno i colori nell'output di debug. | +| `DEBUG_DEPTH` | Profondità dell'ispezione dell'oggetto. | +| `DEBUG_FD` | Descrittore file su cui scrivere l'output di debug. | +| `DEBUG_SHOW_HIDDEN` | Mostra le proprietà nascoste sugli oggetti ispezionati. | + + + +Le variabili di ambiente che iniziano con `DEBUG_` finiscono per essere convertite in un oggetto Opzioni +che viene utilizzato con i formatori `%o`/`%O`. Vedere la documentazione Node.js per +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) per l'elenco completo +. + + diff --git a/src/content/docs/it/4x/guide/error-handling.mdx b/src/content/docs/it/4x/guide/error-handling.mdx new file mode 100644 index 0000000000..affc346d07 --- /dev/null +++ b/src/content/docs/it/4x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Gestione Degli Errori +description: Capire come Express.js gestisce gli errori nel codice sincrono e asincrono e imparare ad implementare middleware gestione degli errori personalizzati per le vostre applicazioni. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Error Handling* si riferisce a come Express cattura ed elabora gli errori +che si verificano in modo sincrono e asincrono. Express viene fornito con un gestore di errore +predefinito quindi non è necessario scrivere il proprio per iniziare. + +## Errori Di Cattura + +È importante garantire che Express colmi tutti gli errori che si verificano mentre +gestisce le rotte e middleware. + +Gli errori che si verificano nel codice sincrono all'interno dei gestori del percorso e del middleware +non richiedono lavoro aggiuntivo. Se il codice sincrono lancia un errore, allora Express catturerà +ed elaborerà esso. Per esempio: + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Express lo catturerà da solo. +}); +``` + +Per gli errori restituiti da funzioni asincrone invocate dai gestori degli itinerari +e middleware, devi passarli alla funzione `next()`, dove Express sarà +catturarli ed elaborarli. Per esempio: + +```js +app.get('/', (req, res, next) => { + fs. eadFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Passa gli errori a Express. + } else { + res. end(dati); + } + }); +}); +``` + +A partire da Express 5, i gestori del percorso e il middleware che restituiscono una Promise +chiameranno automaticamente `next(value)` quando rifiutano o generano un errore. +Per esempio: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = await getUserById(req.params.id); + res.send(user); +}); +``` + +Se `getUserById` genera un errore o rifiuta, `next` verrà chiamato con +l'errore generato o il valore rifiutato. Se non viene fornito alcun valore rifiutato, `next` +verrà chiamato con un oggetto di errore predefinito fornito dal router Express. + +Se passi qualcosa alla funzione `next()` (tranne la stringa `'route'`), +Express considera la richiesta corrente come un errore e salterà qualsiasi +rimanenti funzioni di routing e middleware senza errori. + +Se il callback in una sequenza non fornisce dati, solo errori, è possibile semplificare +questo codice come segue: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +Nell'esempio precedente, `next` è fornito come callback per `fs.writeFile`, +che viene chiamato con o senza errori. Se non c'è errore, viene eseguito il secondo gestore +, altrimenti Express cattura ed elabora l'errore. + +È necessario catturare gli errori che si verificano in codice asincrono invocato dai router o +middleware e passarli a Express per l'elaborazione. Per esempio: + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + next(err); + } + }, 100); +}); +``` + +L'esempio precedente utilizza un blocco `try...catch` per catturare errori nel codice asincrono +e passarli a Express. Se il blocco `prova...catch` +fosse omesso, Express non coglierebbe l'errore dal momento che non fa parte del codice di gestione +sincrono. + +Usa le promesse per evitare l'overhead del blocco `prova...catch` o quando usi le funzioni +che restituiscono le promesse. Per esempio: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + . hen(() => { + throw new Error('BROKEN'); + }) + . atch(next); // Gli errori saranno passati a Express. +}); +``` + +Dal momento che le promesse catturano automaticamente entrambi gli errori sincroni e le promesse rifiutate, +puoi semplicemente fornire `next` come il gestore finale di cattura e Express catturerà errori, +perché al gestore della cattura viene dato l'errore come primo argomento. + +Si potrebbe anche utilizzare una catena di gestori per fare affidamento su errore sincrono +catching, riducendo il codice asincrono a qualcosa di banale. Per esempio: + +```js +app.get('/', [ + function (req, res, next) { + fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals. ata = dati; + next(err); + }); + }, + function (req, res) { + res. ocals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +L'esempio precedente ha un paio di istruzioni banali dalla chiamata `readFile` +. Se `readFile` causa un errore, allora passa l'errore a Express, altrimenti +torna rapidamente al mondo della gestione sincrona degli errori nel prossimo gestore +nella catena. Poi, l'esempio di cui sopra cerca di elaborare i dati. Se questo fallisce, il gestore di errori sincroni +lo catturerà. Se avessi fatto questa elaborazione all'interno di +il callback `readFile`, l'applicazione potrebbe uscire e i gestori dell'errore Express +non sarebbero stati eseguiti. + +Qualunque metodo si utilizzi, se si desidera che i gestori di errori Express siano chiamati dentro e l'applicazione +per sopravvivere, è necessario assicurarsi che Express riceva l'errore. + +## Il gestore degli errori predefinito + +Express è dotato di un gestore di errori integrato che si occupa di eventuali errori che potrebbero essere riscontrati nell'app. Questa funzione middleware di gestione degli errori predefinita viene aggiunta alla fine dello stack della funzione middleware. + +Se passi un errore a `next()` e non lo gestisci in un gestore di errore +personalizzato, sarà gestito dal gestore di errori integrato; l'errore sarà +scritto al client con la traccia dello stack. La traccia dello stack non è inclusa +nell'ambiente di produzione. + + + +Imposta la variabile d'ambiente `NODE_ENV` su `production`, per eseguire l'applicazione in modalità di produzione. + + + +Quando viene scritto un errore, alla risposta +vengono aggiunte le seguenti informazioni: + +* Il `res.statusCode` è impostato da `err.status` (o `err.statusCode`). Se + questo valore è al di fuori dell'intervallo 4xx o 5xx, sarà impostato a 500. +* Il `res.statusMessage` è impostato in base al codice di stato. +* Il corpo sarà l'HTML del messaggio del codice di stato quando in ambiente di produzione + , altrimenti sarà `err.stack`. +* Qualsiasi intestazione specificata in un oggetto `err.headers`. + +Se chiami `next()` con un errore dopo aver iniziato a scrivere la risposta +(ad esempio, se riscontri un errore durante lo streaming della risposta +al client), il gestore di errore predefinito Express chiude la connessione +e non riesce la richiesta. + +Quindi, quando si aggiunge un gestore di errori personalizzato, è necessario delegare a +il gestore di errori Express predefinito, quando le intestazioni +sono già state inviate al client: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Nota che il gestore di errori predefinito può essere attivato se chiami `next()` con un errore +nel tuo codice più di una volta, anche se la gestione degli errori personalizzati è in funzione. + +Altri errori di gestione middleware possono essere trovati su [Express middleware](/en/resources/middleware). + +## Gestione errori di scrittura + +Definire le funzioni middleware per la gestione degli errori allo stesso modo di altre funzioni middleware, +eccetto le funzioni di gestione degli errori hanno quattro argomenti invece di tre: +`(err, req, res, next)`. Per esempio: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Definisci l'ultima gestione degli errori del middleware, dopo altre chiamate `app.use()` e percorsi; per esempio: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser. rlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app. se(methodOverride()); +app.use((err, req, res, next) => { + // logic +}); +``` + +Le risposte da all'interno di una funzione middleware possono essere in qualsiasi formato, come una pagina di errore HTML, un semplice messaggio, o una stringa JSON. + +Per scopi organizzativi (e di framework di livello superiore) è possibile definire diverse funzioni middleware di gestione degli errori +come si farebbe con funzioni di middleware regolari +. Ad esempio, per definire un gestore di errori +per le richieste fatte utilizzando `XHR` e quelle senza: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app. se( + bodyParser.urlencoded({ + extended true, + }) +); +app. se(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +In questo esempio, i `logErrors` generici potrebbero scrivere la richiesta e le informazioni di errore +in `stderr`, per esempio: + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +Anche in questo esempio, `clientErrorHandler` è definito come segue; in questo caso, l'errore viene esplicitamente passato a quello successivo. + +Nota che quando *non* chiama "next" in una funzione di gestione degli errori, sei responsabile della scrittura (e della fine) della risposta. In caso contrario, tali richieste saranno "appese" e non saranno ammissibili per la raccolta rifiuti. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500). end({ error: 'Something failed!' }); + } else { + next(err); + } +} +``` + +Implementa la funzione `errorHandler` "catch-all" come segue (per esempio): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +Se si dispone di un gestore del percorso con molteplici funzioni di callback, è possibile utilizzare il parametro `route` per passare al prossimo gestore del percorso. Per esempio: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user. asPaid) { + // continue handling this request + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent. ind((err, doc) => { + if (err) return next(err); + res. son(doc); + }); + } +); +``` + +In questo esempio, il gestore `getPaidContent` sarà saltato, ma qualsiasi gestore rimanente in `app` per `/a_route_behind_paywall` continuerà ad essere eseguito. + + + +Le chiamate a `next()` e `next(err)` indicano che il gestore corrente è completo e in quale stato. +`next(err)` salterà tutti i gestori rimanenti nella catena ad eccezione di quelli che sono impostati su +gestire gli errori come descritto sopra. + + diff --git a/src/content/docs/it/4x/guide/overriding-express-api.md b/src/content/docs/it/4x/guide/overriding-express-api.md new file mode 100644 index 0000000000..86696c08e0 --- /dev/null +++ b/src/content/docs/it/4x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Sovrascrivendo l'API Express +description: Scopri come personalizzare ed estendere l'API di Express.js sovrascrivendo i metodi e le proprietà su richiesta e gli oggetti di risposta utilizzando prototipi. +--- + +L'API Express è composta da vari metodi e proprietà su richiesta e oggetti di risposta. Questi sono ereditati dal prototipo. Ci sono due punti di estensione per l'API Express: + +1. I prototipi globali in `express.request` e `express.response`. +2. prototipi specifici per app su `app.request` e `app.response`. + +La modifica dei prototipi globali influenzerà tutte le applicazioni Express caricate nello stesso processo. Se lo si desidera, le modifiche possono essere rese specifiche alle app modificando solo i prototipi specifici delle app dopo aver creato una nuova app. + +## Metodi + +È possibile sovrascrivere la firma e il comportamento dei metodi esistenti con il proprio, assegnando una funzione personalizzata. + +Di seguito è riportato un esempio di sovrascrittura del comportamento di [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +L'implementazione di cui sopra cambia completamente la firma originale di `res.sendStatus`. Ora accetta un codice di stato, il tipo di codifica e il messaggio da inviare al client. + +Il metodo overridden può ora essere utilizzato in questo modo: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## Proprietà + +Le proprietà nell'API Express sono: + +1. Proprietà assegnate (es: `req.baseUrl`, `req.originalUrl`) +2. Definito come getters (es: `req.secure`, `req.ip`) + +Poiché le proprietà sotto la categoria 1 sono assegnate dinamicamente sugli oggetti `request` e `response` nel contesto dell'attuale ciclo di richiesta-risposta, il loro comportamento non può essere superato. + +Le proprietà sotto la categoria 2 possono essere sovrascritte utilizzando le API di estensione Express. + +Il seguente codice riscrive come deve essere derivato il valore di `req.ip`. Ora restituisce semplicemente il valore dell'intestazione della richiesta `Client-IP`. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Protototipo + +Al fine di fornire l'API Express, gli oggetti richiesta/risposta passati a Express (tramite `app(req, res)`, per esempio) bisogno di ereditare dalla stessa catena prototipo. Per impostazione predefinita, questo è `http.IncomingRequest.prototype` per la richiesta e `http.ServerResponse.prototype` per la risposta. + +Se non necessario, si raccomanda che ciò avvenga solo a livello di applicazione e non a livello globale. Inoltre, fare in modo che il prototipo che viene utilizzato corrisponda la funzionalità il più vicino possibile ai prototipi predefiniti. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/it/4x/guide/routing.mdx b/src/content/docs/it/4x/guide/routing.mdx new file mode 100644 index 0000000000..4a65c235d4 --- /dev/null +++ b/src/content/docs/it/4x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Routing +description: Scopri come definire e utilizzare i percorsi nelle applicazioni Express.js, inclusi i metodi di percorso, i percorsi e i parametri e utilizzando Router per il routing modulare. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* si riferisce a come gli endpoint di un'applicazione (URI) rispondono alle richieste del client. +Per un'introduzione al routing, vedere [Instradamento di base](/en/starter/basic-routing). + +Definisci il routing usando metodi dell'oggetto `app` Express che corrispondono ai metodi HTTP; +per esempio, `app. et()` per gestire le richieste GET e `app.post` per gestire le richieste POST. Per una lista completa, +vedi [app.METHOD](/en/5x/api#app.METHOD). Puoi anche usare [app.all()](/en/5x/api#app.all) per gestire tutti i metodi HTTP e [app. se()](/en/5x/api#app.use) to +specify middleware as the callback function (Vedi [Using middleware](/en/guide/using-middleware) for details). + +Questi metodi di routing specificano una funzione di callback (a volte chiamata "funzioni di handler") chiamata quando l'applicazione riceve una richiesta al percorso specificato (endpoint) e il metodo HTTP. In altre parole, l'applicazione "ascolta" per le richieste che corrispondono ai percorsi e ai metodi specificati, e quando rileva una corrispondenza, chiama la funzione di callback specificata. + +Infatti, i metodi di routing possono avere più di una funzione di callback come argomenti. +Con funzioni di callback multiple, è importante fornire `next` come argomento alla funzione di callback e poi chiamare `next()` all'interno del corpo della funzione per consegnare il controllo +al prossimo callback. + +Il seguente codice è un esempio di un percorso molto basilare. + +```js +const express = require('express'); +const app = express(); + +// rispondi con "ciao mondo" quando una richiesta GET viene fatta all'app homepage +. et('/', (req, res) => { + res.send('hello world'); +}); +``` + +## Metodi percorso + +Un metodo di percorso è derivato da uno dei metodi HTTP ed è collegato ad un'istanza della classe `express`. + +Il seguente codice è un esempio di percorsi definiti per il `GET` e i metodi `POST` nella root dell'app. + +```js +// GET method route +app.get('/', (req, res) => { + res. end('Richiesta GET alla homepage'); +}); + +// POST metodo percorso +app. ost('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Express supporta metodi che corrispondono a tutti i metodi di richiesta HTTP: `get`, `post`, e così via. +Per un elenco completo, vedere [app.METHOD](/en/5x/api#app.METHOD). + +C'è un metodo di routing speciale, `app.all()`, utilizzato per caricare le funzioni middleware in un percorso per *tutti* i metodi di richiesta HTTP. Ad esempio, il seguente gestore viene eseguito per le richieste al percorso `"/secret"` se si utilizza `GET`, `POST`, `PUT`, `DELETE`, o qualsiasi altro metodo di richiesta HTTP supportato nel [modulo http](https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Accedere alla sezione segreta ...'); + next(); // passare il controllo al prossimo gestore +}); +``` + +## Percorsi di rotta + +Percorsi di percorso, in combinazione con un metodo di richiesta, definire gli endpoint in cui le richieste possono essere fatte. I tracciati del percorso possono essere stringhe, motivi di stringa o espressioni regolari. + + + +In express 5, i personaggi `? , `+`, `\*`, `[]`, e `()\` sono gestiti in modo diverso rispetto alla versione +4, si prega di rivedere la [guida alla migrazione](/en/guide/migrating-5#path-syntax) per maggiori informazioni. + + + + + +Nell'espressione 4, i caratteri di espressione regolare come `$` devono essere fuggiti con un `\`. + + + + + +Express utilizza [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) per abbinare i percorsi del percorso +; vedere la documentazione path-to-regexp per tutte le possibilità di definire i percorsi del percorso. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) è uno strumento utile per +testare i percorsi Express di base, anche se non supporta la corrispondenza dei modelli. + + + +Le stringhe di query non fanno parte del percorso percorso. + +### Percorsi di percorso basati su stringhe + +Questo percorso corrisponderà alle richieste del percorso root, `/`. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +Questo percorso corrisponderà alle richieste di `/about`. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +Questo percorso corrisponderà alle richieste a `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Percorsi del percorso in base ai motivi delle stringhe + + + +I modelli di stringhe in Express 5 non funzionano più. Si prega di fare riferimento alla [guida di migrazione +(/en/guide/migrating-5#path-syntax) per ulteriori informazioni. + + + +Questo percorso corrisponde a `acd` e `abcd`. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +Questo percorso corrisponderà a `abcd`, `abbcd`, `abbbcd`, e così via. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +Questo percorso corrisponde a `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd`, e così via. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +Questo percorso corrisponde a `/abe` e `/abcde`. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Percorsi di percorso basati su espressioni regolari + +Questo percorso corrisponderà a qualsiasi cosa con una "a" in esso. + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +Questo percorso corrisponde a `butterfly` e `dragonfly`, ma non a `butterflyman`, `dragonflyman`, e così via. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Parametri percorso + +I parametri del percorso sono denominati segmenti di URL che vengono utilizzati per catturare i valori specificati nella loro posizione nell'URL. I valori catturati sono popolati nell'oggetto `req.params`, con il nome del parametro route specificato nel percorso come loro rispettive chiavi. + +``` +Percorso del percorso: /users/:userId/books/:bookId +Richiedi URL: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +Per definire i percorsi con i parametri del percorso, è sufficiente specificare i parametri del percorso nel percorso come mostrato di seguito. + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +Il nome dei parametri del percorso deve essere composto da "caratteri di parola" ([A-Za-z0-9_]). + + + +Poiché il trattino (`-`) e il punto (`.`) sono interpretati letteralmente, possono essere utilizzati insieme ai parametri del percorso per scopi utili. + +``` +Percorso del percorso: /flights/:from-:to +Richiedi URL: http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Percorso percorso: /plantae/:genus.:species +Richiedi URL: http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +In express 5, Regexp characters are not supported in route paths, for more information please +refer to the [migration guide](/en/guide/migrating-5#path-syntax). + + + +Per avere più controllo sulla stringa esatta che può essere abbinata a un parametro del percorso, puoi aggiungere un'espressione regolare tra parentesi (`()`): + +``` +Percorso del percorso: /user/:userId(\d+) +Richiedi URL: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Perché l'espressione regolare è di solito parte di una stringa letterale, assicurati di sfuggire a qualsiasi carattere `\` +con un backslash aggiuntivo, ad esempio `\d+`. + + + + +In Express 4.x, il carattere `*` nelle espressioni regolari non viene interpretato nel modo usuale. Come soluzione puoi usare `{0,}` invece di `*`. Questo sarà probabilmente fissato in Express 5. + + +## Gestori del percorso + +È possibile fornire più funzioni di callback che si comportano come [middleware](/en/guide/using-middleware) per gestire una richiesta. L'unica eccezione è che questi callback potrebbero invocare `next('route')` per bypassare i rimanenti callback del percorso. È possibile utilizzare questo meccanismo per imporre condizioni preliminari su un percorso, poi passare il controllo ai percorsi successivi se non c'è motivo di procedere con il percorso corrente. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params. d === '0') { + return next('route'); + } + res. end(`User ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Special handler for user ID 0'); +}); +``` + +In questo esempio: + +* `GET /user/5` → gestito dal primo percorso → invia "User 5" +* `GET /user/0` → prima rotta chiama `next('route')`, saltando al prossimo percorso corrispondente `/user/:id` + +I gestori del percorso possono essere nella forma di una funzione, una serie di funzioni, o combinazioni di entrambi, come mostrato negli esempi seguenti. + +Una singola funzione di callback può gestire un percorso. Per esempio: + +```js +app.get('/example/a', (req, res) => { + res.send('Hello from A!'); +}); +``` + +Più di una funzione di callback può gestire un percorso (assicurati di specificare l'oggetto `next`). Per esempio: + +```js +app.get( + '/example/b', + (req, res, next) => { + console. og('la risposta verrà inviata dalla funzione successiva . .'); + next(); + }, + (req, res) => { + res. end('Ciao da B!'); + } +); +``` + +Un array di funzioni di callback può gestire un percorso. Per esempio: + +```js +const cb0 = function (req, res, next) { + console. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +const cb2 = function (req, res) { + res. end('Ciao da C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +Una combinazione di funzioni indipendenti e matrici di funzioni può gestire un percorso. Per esempio: + +```js +const cb0 = function (req, res, next) { + console. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +app. et( + '/example/d', + [cb0, cb1], + (req, res, next) => { + console. og('la risposta verrà inviata dalla funzione successiva . .'); + next(); + }, + (req, res) => { + res. end('Ciao da D!'); + } +); +``` + +## Metodi di risposta + +I metodi sull'oggetto di risposta (`res`) nella tabella seguente possono inviare una risposta al client e terminare il ciclo di richiesta-risposta. Se nessuno di questi metodi è chiamato da un gestore del percorso, la richiesta del cliente sarà sospesa. + +| Metodo | Descrizione | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| [res.download()](/en/5x/api#res.download) | Avverte un file da scaricare. | +| [res.end()](/en/5x/api#res.end) | Termina il processo di risposta. | +| [res.json()](/en/5x/api#res.json) | Invia una risposta JSON. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Invia una risposta JSON con il supporto JSONP. | +| [res.redirect()](/en/5x/api#res.redirect) | Reindirizza una richiesta. | +| [res.render()](/en/5x/api#res.render) | Render un modello di visualizzazione. | +| [res.send()](/en/5x/api#res.send) | Invia una risposta di vari tipi. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Invia un file come un flusso di otte. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Imposta il codice di stato della risposta e invia la sua rappresentazione della stringa come corpo della risposta. | + +## app.route() + +È possibile creare i gestori di rotte per un percorso utilizzando `app.route()`. +Poiché il percorso è specificato in una singola posizione, è utile creare percorsi modulari, così come ridurre la ridondanza e pneumatici. Per ulteriori informazioni sulle rotte, si veda: [Router() documentation](/en/5x/api#router). + +Ecco un esempio di router incatenati che sono definiti utilizzando `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res. end('Ottieni un libro casuale'); + }) + . ost((req, res) => { + res.send('Add a book'); + }) + . ut((req, res) => { + res.send('Aggiorna il libro'); +}); +``` + +## express.Router + +Usa la classe `express.Router` per creare i gestori modulari e montabili. Un'istanza `Router` è un sistema di routing e middleware completo; per questo motivo è spesso chiamata "mini-app". + +L'esempio seguente crea un router come modulo, carica una funzione middleware in esso, definisce alcuni percorsi e monta il modulo del router su un percorso nell'app principale. + +Crea un file router chiamato `birds.js` nella directory delle app, con il seguente contenuto: + +```js +const express = require('express'); +const router = express. outer(); + +// middleware che è specifico per questo router +const timeLog = (req, res, next) => { + console. og('Orario: ', Date.now()); + next(); +}; +router. se(timeLog); + +// definisci il percorso della home page +router.get('/', (req, res) => { + res. end('Birds home page'); +}); +// definire il router sulla rotta +. et('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Quindi, caricare il modulo router nell'app: + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +L'app sarà ora in grado di gestire le richieste di `/birds` e `/birds/about`, oltre a chiamare la funzione middleware `timeLog` che è specifica per il percorso. + +Ma se il percorso principale `/birds` ha parametri di percorso, non sarà accessibile per impostazione predefinita dai sotto-percorsi. Per renderlo accessibile, dovrai passare l'opzione `mergeParams` al costruttore Router [reference](/en/5x/api#app.use). + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/it/4x/guide/using-middleware.mdx b/src/content/docs/it/4x/guide/using-middleware.mdx new file mode 100644 index 0000000000..d076967bee --- /dev/null +++ b/src/content/docs/it/4x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Usare middleware +description: Scopri come utilizzare middleware nelle applicazioni Express.js, tra cui middleware a livello di applicazione e router, gestione degli errori e integrazione di middleware di terze parti. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express è un framework web routing e middleware che ha funzionalità minime proprie: Un'applicazione Express è essenzialmente una serie di chiamate di funzioni middleware. + +Le funzioni *Middleware* sono funzioni che hanno accesso al [request object](/en/5x/api#req) (`req`), il [response object](/en/5x/api#res) (`res`), e la successiva funzione middleware nel ciclo request-response dell'applicazione. La funzione middleware successiva è comunemente indicata da una variabile chiamata `next`. + +Le funzioni Middleware possono eseguire le seguenti attività: + +* Esegue qualsiasi codice. +* Effettuare modifiche alla richiesta e agli oggetti di risposta. +* Terminare il ciclo richiesta-risposta. +* Chiama la funzione middleware successiva nello stack. + +Se la funzione middleware corrente non termina il ciclo richiesta-risposta, deve chiamare `next()` per passare il controllo alla successiva funzione middleware. In caso contrario, la richiesta sarà sospesa. + +Un'applicazione Express può utilizzare i seguenti tipi di middleware: + +* [Application-level middleware](#middleware.application) +* [Router-level middleware](#middleware.router) +* [Gestione errori middleware](#middleware.error-handling) +* [Built-in middleware](#middleware.built-in) +* [middleware di terze parti](#middleware.third-party) + +È possibile caricare il middleware a livello di applicazione e router con un percorso di montaggio opzionale. +È inoltre possibile caricare una serie di funzioni middleware insieme, che crea una sottopila del sistema middleware in un punto di montaggio. + +## Middleware a livello di applicazione + +Associa il middleware di livello applicativo ad un'istanza del [app object](/en/5x/api#app) usando `app.use()` e `app. ETHOD()` funzioni, dove `METHOD` è il metodo HTTP della richiesta che la funzione middleware gestisca (come GET, PUT, o POST) in minuscolo. + +Questo esempio mostra una funzione middleware senza percorso di montaggio. La funzione viene eseguita ogni volta che l'app riceve una richiesta. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +Questo esempio mostra una funzione middleware montata sul percorso `/user/:id`. La funzione viene eseguita per qualsiasi tipo di richiesta HTTP +sul percorso `/user/:id`. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +Questo esempio mostra un percorso e la sua funzione di gestore (sistema middleware). La funzione gestisce le richieste GET al percorso `/user/:id`. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +Ecco un esempio di caricamento di una serie di funzioni middleware in un punto di montaggio, con un percorso di montaggio. +Illustra un sub-stack middleware che stampa la richiesta di informazioni per qualsiasi tipo di richiesta HTTP al percorso `/user/:id`. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + console. og('Request Type:', req.method); + next(); + } +); +``` + +I gestori del percorso consentono di definire percorsi multipli per un percorso. L'esempio sottostante definisce due percorsi per le richieste GET al percorso `/user/:id`. Il secondo percorso non causerà alcun problema, ma non verrà mai chiamato perché il primo percorso termina il ciclo richiesta-risposta. + +Questo esempio mostra un sub-stack middleware che gestisce le richieste GET al percorso `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req. arams.id); + next(); + }, + (req, res, next) => { + res. end('Info utente'); + } +); + +// handler per il percorso /user/:id, che stampa l'app ID utente +. et('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +Per saltare il resto delle funzioni middleware da uno stack middleware router, chiama `next('route')` per passare il controllo al percorso successivo. + + + +`next('route')` will work only in middleware functions that were loaded by using the +`app.METHOD()` or `router.METHOD()` functions. + + + +Questo esempio mostra un sub-stack middleware che gestisce le richieste GET al percorso `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + // se l'ID utente è 0, salta al prossimo percorso + se (req. arams. d === '0') next('route'); + // altrimenti passa il controllo alla funzione middleware successiva in questo stack + altrimenti successivo(); + }, + (req, res, next) => { + // invia una risposta regolare + res. end('regular'); + } +); + +// handler per il percorso /user/:id, che invia una risposta speciale +app. et('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +Middleware può anche essere dichiarato in un array per la riutilizzabilità. + +Questo esempio mostra un array con un sub-stack middleware che gestisce le richieste GET al percorso `/user/:id` + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req. riginalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Request Type:', req. ethod); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app. et('/user/:id', logStuff, (req, res, next) => { + res.send('User Info'); +}); +``` + +## Router-level middleware + +Router-level middleware funziona allo stesso modo di application-level middleware, tranne che è legato ad un'istanza di `express.Router()`. + +```js +router const = express.Router(); +``` + +Carica il middleware a livello router usando le funzioni `router.use()` e `router.METHOD()`. + +Il seguente esempio di codice replica il sistema middleware che viene mostrato sopra per il middleware a livello di applicazione, utilizzando il middleware a livello di router: + +```js +const express = require('express'); +const app = express(); +const router = express. outer(); + +// una funzione middleware senza percorso di montaggio. Questo codice viene eseguito per ogni richiesta al router +. se((req, res, next) => { + console.log('Time:', Date. ow()); + next(); +}); + +// un sub-stack middleware mostra le informazioni di richiesta per qualsiasi tipo di richiesta HTTP al router /user/:id path +. se( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + console. og('Request Type:', req. ethod); + next(); + } +); + +// un sub-stack middleware che gestisce le richieste GET al router /user/:id path +. et( + '/user/:id', + (req, res, next) => { + // se l'ID utente è 0, salta al router successivo + se (req. arams. d === '0') next('route'); + // altrimenti passa il controllo alla successiva funzione middleware in questo stack + altrimenti successivo(); + }, + (req, successivo) => { + // renderizza una pagina normale + res. ender('regular'); + } +); + +// handler per il percorso /user/:id, che rende una pagina speciale +router. et('/user/:id', (req, res, next) => { + console. og(req.params.id); + res.render('special'); +}); + +// monta il router sull'app +app.use('/', router); +``` + +Per saltare il resto delle funzioni middleware del router, chiama `next('router')` +per passare il controllo indietro dall'istanza del router. + +Questo esempio mostra un sub-stack middleware che gestisce le richieste GET al percorso `/user/:id`. + +```js +const express = require('express'); +const app = express(); +const router = express. outer(); + +// predicare il router con un controllo e salvataggio quando necessario router +. se((req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router. et('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// usa il router e 401 qualsiasi cosa che cade attraverso l'app +. se('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## middleware gestione errori + + + +La gestione degli errori del middleware richiede sempre *four* argomenti. È necessario fornire quattro argomenti per +identificarlo come una funzione middleware di gestione degli errori. Anche se non è necessario utilizzare l'oggetto `next` +, è necessario specificarlo per mantenere la firma. Otherwise, the `next` object will be +interpreted as regular middleware and will fail to handle errors. + + + +Definire le funzioni middleware per la gestione degli errori allo stesso modo di altre funzioni middleware, tranne con quattro argomenti invece di tre, specificatamente con la firma `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Per maggiori dettagli sulla gestione degli errori middleware, vedere [Gestione degli errori](/en/guide/error-handling). + +## Middleware incorporato + +A partire dalla versione 4.x, Express non dipende più da [Connect](https://github.com/senchalabs/connect). Le funzioni middleware +che erano state precedentemente incluse con Express sono ora in moduli separati; vedi [la lista delle funzioni middleware](https://github.com/senchalabs/connect#middleware). + +Express ha le seguenti funzioni middleware integrate: + +* [express.static](/en/5x/api#express.static) serve risorse statiche come file HTML, immagini e così via. +* [express.json](/en/5x/api#express.json) analizza le richieste in arrivo con i payload JSON. **NOTA: Disponibile con Express 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) analizza le richieste in arrivo con payload codificati con URL. **NOTA: Disponibile con Express 4.16.0+** + +## middleware di terze parti + +Usa middleware di terze parti per aggiungere funzionalità alle app Express. + +Installare il modulo Node.js per le funzionalità richieste, quindi caricarlo nell'app a livello di applicazione o a livello di router. + +L'esempio seguente illustra l'installazione e il caricamento della funzione middleware di analisi dei cookie `cookie-parser`. + +```bash +$ npm install cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// load the cookie-parsing middleware +app.use(cookieParser()); +``` + +Per una lista parziale delle funzioni middleware di terze parti che sono comunemente usate con Express, vedere [middleware di terze parti](../resources/middleware). diff --git a/src/content/docs/it/4x/guide/using-template-engines.mdx b/src/content/docs/it/4x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..b9ca68f319 --- /dev/null +++ b/src/content/docs/it/4x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Utilizzo di modelli di motori con Express +description: Scopri come integrare e utilizzare modelli di motori come Pug, Manubri ed EJS con Express.js per rendere le pagine HTML dinamiche in modo efficiente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Un motore *modello* ti permette di utilizzare file di template statici nella tua applicazione. Al runtime, il modello del motore sostituisce le variabili +in un modello di file con valori reali, e trasforma il modello in un file HTML inviato al client. +Questo approccio rende più facile progettare una pagina HTML. + +Il [generatore di applicazioni Express](/en/starter/generator) utilizza [Pug](https://pugjs.org/api/getting-started.html) come predefinito, ma supporta anche [Handlebars](https://www.npmjs.com/package/handlebars), e [EJS](https://www.npmjs.com/package/ejs), tra gli altri. + +Per rendere i file dei modelli, imposta le seguenti [proprietà delle impostazioni dell'applicazione](/en/4x/api#app.set), nel file `app.js` predefinito creato dal generatore: + +* `views`, la directory dove si trovano i file del modello. Eg: `app.set('views', './views')`. + Questo valore predefinito è la directory `views` nella directory radice dell'applicazione. +* `view engine`, il modello motore da usare. Ad esempio, per usare il motore modello Pug: `app.set('view engine', 'pug')`. + +Quindi installare il corrispondente pacchetto npm del motore del modello; per esempio per installare Pug: + +```bash +$ npm install pug --save +``` + + +Motori di modelli conformi ad espresso, come Pug esportano una funzione chiamata `__express(filePath, options, callback)`, +che `res.render()` chiama per rendere il codice del modello. + +Alcuni modelli di motori non seguono questa convenzione. La libreria [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +segue questa convenzione mappando tutti i popolari motori di template Node.js, e quindi funziona perfettamente all'interno di Express. + + + +Dopo che il motore di visualizzazione è stato impostato, non è necessario specificare il motore o caricare il modulo del motore modello nella tua app; +Express carica il modulo internamente, per esempio: + +```js +app.set('view engine', 'pug'); +``` + +Quindi, crea un file modello Pug chiamato `index.pug` nella directory `views`, con il seguente contenuto: + +```pug +html + head + title= title + body + h1= message +``` + +Crea un percorso per rendere il file `index.pug`. Se la proprietà `view engine` non è impostata, +è necessario specificare l'estensione del file `view`. Altrimenti, puoi ometterlo. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +Quando effettui una richiesta alla home page, il file `index.pug` verrà renderizzato come HTML. + +La cache del motore di visualizzazione non memorizza in cache il contenuto dell'output del modello, solo il modello sottostante. La vista è ancora ri-renderizzata con ogni richiesta anche quando la cache è accesa. diff --git a/src/content/docs/it/4x/guide/writing-middleware.mdx b/src/content/docs/it/4x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..ef60a1ae15 --- /dev/null +++ b/src/content/docs/it/4x/guide/writing-middleware.mdx @@ -0,0 +1,239 @@ +--- +title: Scrittura middleware per l'utilizzo in applicazioni Express +description: Scopri come scrivere funzioni middleware personalizzate per le applicazioni Express.js, inclusi esempi e migliori pratiche per migliorare la gestione delle richieste e delle risposte. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Le funzioni *Middleware* sono funzioni che hanno accesso al [request object](/en/5x/api#req) (`req`), il [response object](/en/5x/api#res) (`res`), e la funzione `next` nel ciclo request-response dell'applicazione. La funzione `next` è una funzione nel router Express che, quando invocato, esegue il middleware con successo al middleware corrente. + +Le funzioni Middleware possono eseguire le seguenti attività: + +* Esegue qualsiasi codice. +* Effettuare modifiche alla richiesta e agli oggetti di risposta. +* Terminare il ciclo richiesta-risposta. +* Chiama il prossimo middleware nello stack. + +Se la funzione middleware corrente non termina il ciclo richiesta-risposta, deve chiamare `next()` per passare il controllo alla successiva funzione middleware. In caso contrario, la richiesta sarà sospesa. + +La figura seguente mostra gli elementi di una chiamata di una funzione middleware: + +
+ + + + + +
+Elementi di una chiamata a funzione middleware + +Metodo
HTTP per il quale si applica la funzione middleware.
+ +
+ Percorso (percorso) per il quale si applica la funzione middleware. +
+ +
+ La funzione middleware. +
+ +
+ Argomento di richiamo alla funzione middleware, chiamato "next" per convenzione. +
+ +
+ Argomento HTTP risposta alla funzione middleware, chiamato "res" dalla convenzione + . +
+ +
HTTP richiede l'argomento alla funzione middleware, chiamata "req" per convenzione.
+
+
+ +A partire da Express 5, le funzioni middleware che restituiscono una Promise chiameranno `next(value)` quando rifiutano o lanciano un errore. `next` verrà chiamato con il valore rifiutato o con l'errore lanciato. + +## Esempio + +Ecco un esempio di una semplice applicazione "Hello World" Express. +Il resto di questo articolo definirà e aggiungerà tre funzioni middleware all'applicazione: +uno chiamato `myLogger` che stampa un semplice messaggio di registro, uno chiamato `requestTime` che +visualizza il timestamp della richiesta HTTP e uno chiamato `validateCookies` che convalida i cookie in entrata. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +### Funzione middleware myLogger + +Ecco un semplice esempio di una funzione middleware chiamata "myLogger". Questa funzione solo stampa +"LOGGED" quando una richiesta all'app passa attraverso di essa. La funzione middleware è assegnata a una variabile +chiamata `myLogger`. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +Notare la chiamata sopra a `next()`. Chiamando questa funzione invoca la prossima funzione middleware nell'app +. La funzione `next()` non è una parte del Node. s o Express API, ma è il terzo argomento +che viene passato alla funzione middleware. La funzione `next()` potrebbe essere chiamata qualsiasi cosa, +ma per convenzione è sempre chiamata "next". Per evitare confusione, utilizzare sempre questa convenzione. + + + +Per caricare la funzione middleware, chiama `app.use()`, specificando la funzione middleware. +Ad esempio, il seguente codice carica la funzione middleware `myLogger` prima del percorso al percorso root (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console. og('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Ciao World!'); +}); + +app.listen(3000); +``` + +Ogni volta che l'app riceve una richiesta, stampa il messaggio "LOGGED" al terminale. + +L'ordine di caricamento del middleware è importante: le funzioni middleware che vengono caricate per primo vengono eseguite per prime. + +Se il file `myLogger` viene caricato dopo il percorso verso il percorso root, la richiesta non lo raggiunge mai e l'applicazione non stampa "LOGGED", perché il gestore del percorso del percorso radice termina il ciclo richiesta-risposta. + +La funzione middleware `myLogger` semplicemente stampa un messaggio, poi passa la richiesta alla funzione middleware successiva nello stack chiamando la funzione `next()`. + +### Richiesta funzione Middleware + +Successivamente, creeremo una funzione middleware chiamata "requestTime" e aggiungeremo una proprietà chiamata `requestTime` +all'oggetto richiesta. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +L'app utilizza ora la funzione middleware `requestTime`. Inoltre, la funzione callback del percorso del percorso del percorso di root utilizza la proprietà che la funzione middleware aggiunge a `req` (il oggetto richiesta). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req. equestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app. et('/', (req, res) => { + let responseText = 'Ciao Mondo!
'; + responseText += `Richiesto a: ${req.requestTime}`; + res. end(responseText); +}); + +app.listen(3000); +``` + +Quando si effettua una richiesta alla root dell'app, l'app ora visualizza il timestamp della richiesta nel browser. + +### Middleware function validateCookies + +Infine, creeremo una funzione middleware che convalida i cookie in arrivo e invia una risposta 400 se i cookie non sono validi. + +Ecco una funzione di esempio che convalida i cookie con un servizio asincronico esterno. + +```js +async function cookieValidator(cookies) { + try { + await externallyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Invalid cookies'); + } +} +``` + +Qui utilizziamo il middleware [`cookie-parser`](/en/resources/middleware/cookie-parser) per analizzare i cookie in arrivo fuori dall'oggetto `req` e passarli alla nostra funzione `cookieValidator`. Il middleware `validateCookies` restituisce una Promessa che al momento del rifiuto attiverà automaticamente il nostro gestore di errori. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('. cookieValidator'); + +const app = express(); + +async function validateCookies(req, res, next) { + await cookieValidator(req. ookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// error handler +app. se((err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Nota come `next()` viene chiamato dopo `await cookieValidator(req.cookies)`. Questo assicura che se +`cookieValidator` si risolve, il prossimo middleware nello stack verrà chiamato. Se passi qualcosa +alla funzione `next()` (tranne la stringa `'route'` o `'router'`), Espresso considera l'attuale richiesta +come un errore e salterà tutte le rimanenti funzioni di routing e middleware +. + + + +Poiché hai accesso all'oggetto richiesta, all'oggetto risposta, alla funzione middleware successiva nello stack, e all'intero Node. s API, le possibilità con funzioni middleware sono infinite. + +Per ulteriori informazioni su middleware Express, consultare: [Using Express middleware](/en/guide/using-middleware). + +## Middleware configurabile + +Se hai bisogno del tuo middleware per essere configurabile, esporta una funzione che accetta un oggetto di opzioni o altri parametri, che, poi, restituisce l'implementazione middleware in base ai parametri di input. + +File: `my-middleware.js` + +```js +modulo. xports = function (options) { + return function (req, res, next) { + // Implementa la funzione middleware basata sulle opzioni object + next(); + }; +}; +``` + +Il middleware può ora essere utilizzato come mostrato di seguito. + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Fare riferimento a [cookie-session](https://github.com/expressjs/cookie-session) e [compression](https://github.com/expressjs/compression) per esempi di middleware configurabile. diff --git a/src/content/docs/it/4x/starter/basic-routing.mdx b/src/content/docs/it/4x/starter/basic-routing.mdx new file mode 100644 index 0000000000..e78f4b9025 --- /dev/null +++ b/src/content/docs/it/4x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Instradamento base +description: Impara i fondamenti del routing nelle applicazioni Express.js, tra cui come definire i percorsi, gestire i metodi HTTP e creare gestori del percorso per il tuo server web. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* si riferisce alla determinazione di come un'applicazione risponde a una richiesta di client a un determinato endpoint, che è un URI (o percorso) e un metodo di richiesta HTTP specifico (GET, POST, e così via). + +Ogni percorso può avere una o più funzioni di gestore, che vengono eseguite quando il percorso è abbinato. + +La definizione del percorso assume la seguente struttura: + +```js +app.METHOD(PATH, HANDLER); +``` + +Dove: + +* `app` è un'istanza di `express`. +* `METHOD` è un [metodo di richiesta HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in minuscolo. +* `PATH` è un percorso sul server. +* `HANDLER` è la funzione eseguita quando il percorso è corrispondente. + + + +Questo tutorial presuppone che venga creata un'istanza di `express` chiamata `app` e che il server sia in esecuzione +. Se non hai familiarità con la creazione di un'app e l'avvio, vedi l'esempio Ciao mondo +. + + + +Gli esempi che seguono illustrano la definizione di itinerari semplici. + +Rispondi con `Ciao Mondo!` nella homepage: + +```js +app.get('/', (req, res) => { + res.send('Hello World!'); +}); +``` + +Rispondi a una richiesta POST sul percorso radice (`/`), la home page dell'applicazione: + +```js +app.post('/', (req, res) => { + res.send('Got a POST request'); +}); +``` + +Rispondi a una richiesta PUT al percorso `/user`: + +```js +app.put('/user', (req, res) => { + res.send('Got a PUT request at /user'); +}); +``` + +Rispondi a una richiesta DELETE al percorso `/user`: + +```js +app.delete('/user', (req, res) => { + res.send('Got a DELETE request at /user'); +}); +``` + +Per maggiori dettagli sul routing, consulta la [guida di routing](/en/guide/routing). diff --git a/src/content/docs/it/4x/starter/examples.mdx b/src/content/docs/it/4x/starter/examples.mdx new file mode 100644 index 0000000000..a1d1b331f8 --- /dev/null +++ b/src/content/docs/it/4x/starter/examples.mdx @@ -0,0 +1,45 @@ +--- +title: Esempi espressi +description: Esplora una raccolta di esempi di applicazioni Express.js che coprono vari casi di utilizzo, integrazioni e configurazioni avanzate per aiutarti a imparare e costruire i tuoi progetti. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Autenticazione con login e password +* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - Negoziazione di contenuti HTTP +* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Lavorare con sessioni basate su cookie +* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Lavorare con i cookie +* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Trasferimento dei file al client +* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Lavorare con il template JavaScript incorporato (ejs) +* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Creazione pagine di errore +* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Lavorare con middleware errore +* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Gestore semplice della richiesta +* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown come modello motore +* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Lavorare con più router Express +* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - controller in stile MVC +* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Monitoraggio delle attività degli utenti online con pacchetti `online` e `redis` +* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Lavorare con i parametri del percorso +* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Operazioni HTTP multiple sulla stessa risorsa +* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organizzare i percorsi utilizzando una mappa +* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Lavorare con il middleware del percorso +* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizzare percorsi per ogni risorsa +* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Cerca API +* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - sessioni utente +* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Servire file statici +* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Lavorare con gli host virtuali +* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Visualizzazione dinamica +* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Salvataggio dei dati nell'oggetto richiesta tra le chiamate middleware +* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Servizio API semplice + +## Esempi aggiuntivi + +Questi sono alcuni esempi aggiuntivi con integrazioni più estese. + + + Queste informazioni si riferiscono a siti, prodotti o moduli di terze parti che non sono mantenuti dal team + Expressjs. L'elenco qui non costituisce un'approvazione o una raccomandazione da parte del team di progetto + Expressjs. + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app con Express e Next.js utilizzando [Prisma](https://www.npmjs.com/package/prisma) come ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM diff --git a/src/content/docs/it/4x/starter/faq.md b/src/content/docs/it/4x/starter/faq.md new file mode 100644 index 0000000000..6e30b48782 --- /dev/null +++ b/src/content/docs/it/4x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: FAQ +description: Trova le risposte alle domande più frequenti su Express.js, inclusi argomenti sulla struttura delle applicazioni, modelli, autenticazione, modelli motori, gestione degli errori e altro ancora. +--- + +## Come dovrei strutturare la mia applicazione? + +Non esiste una risposta definitiva a questa domanda. La risposta dipende da +sulla scala della tua applicazione e del team che è coinvolto. Per essere il più flessibile possibile +, Express non fa ipotesi in termini di struttura. + +Le rotte e altre logiche specifiche per le applicazioni possono vivere in tutti i file +che desideri, in qualsiasi struttura di directory che preferisci. Visualizza i seguenti esempi di ispirazione +: + +- [Elenco delle rotte](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Mappa del percorso](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Inoltre, ci sono estensioni di terze parti per Express, che semplificano alcuni di questi modelli: + +- [Instradamento delle risorse](https://github.com/expressjs/express-resource) + +## Come definisco i modelli? + +Express non ha alcuna nozione di banca dati. Questo concetto è +lasciato fino a moduli Nodo di terze parti, consentendo di +interfaccia con quasi tutti i database. + +Vedi [LoopBack](http://loopback.io) per un framework basato su Espresso che è centrato sui modelli. + +## Come posso autenticare gli utenti? + +L'autenticazione è un'altra area opinionata in cui Express non si avventura +. È possibile utilizzare qualsiasi schema di autenticazione desiderato. +Per un semplice schema username / password, vedere [questo esempio](https://github.com/expressjs/express/tree/master/examples/auth). + +## Quali modelli di motori supporta Express? + +Express supporta qualsiasi modello di motore conforme alla firma `(percorso, locale, callback)`. +Per normalizzare i modelli di interfacce motore e caching, vedere il progetto +[consolidate.js](https://github.com/visionmedia/consolidate.js) +per il supporto. Motori modello non elencati potrebbero ancora supportare la firma Express. + +Per ulteriori informazioni, vedere [Utilizzo di modelli di motori con Express](/en/guide/using-template-engines). + +## Come posso gestire 404 risposte? + +In Express, 404 risposte non sono il risultato di un errore, quindi +il middleware del gestore dell'errore non le catturerà. Questo comportamento è +perché una risposta 404 indica semplicemente l'assenza di lavoro supplementare da fare; +in altre parole, Express ha eseguito tutte le funzioni e i percorsi del middleware, +e ha trovato che nessuno di loro ha risposto. Tutto quello che devi fare +è aggiungere una funzione middleware nella parte inferiore dello stack (sotto tutte le altre funzioni) +per gestire una risposta 404: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Aggiungi percorsi dinamicamente al runtime su un'istanza di `express.Router()` +in modo che i percorsi non siano sostituiti da una funzione middleware. + +## Come faccio a configurare un gestore di errori? + +Definisci middleware per la gestione degli errori allo stesso modo di altri middleware, +tranne con quattro argomenti invece di tre; specificatamente con la firma `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Per ulteriori informazioni, vedere [Gestione degli errori](/en/guide/error-handling). + +## Come faccio a rendere semplice HTML? + +Non lo fate! Non c'è bisogno di "render" HTML con la funzione `res.render()`. +Se hai un file specifico, usa la funzione `res.sendFile()`. +Se stai servendo molti asset da una directory, usa la funzione middleware `express.static()` +. + +## Quale versione di Node.js richiede Express? + +- [Express 4.x](/en/4x/api) richiede Node.js 0.10 o superiore. +- [Express 5.x](/en/5x/api) richiede Node.js 18 o superiore. diff --git a/src/content/docs/it/4x/starter/generator.mdx b/src/content/docs/it/4x/starter/generator.mdx new file mode 100644 index 0000000000..c7504927ad --- /dev/null +++ b/src/content/docs/it/4x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Generatore di applicazioni espresso +description: Scopri come utilizzare lo strumento del generatore di applicazioni Express per creare rapidamente uno scheletro per le applicazioni Express.js, semplificando la configurazione e la configurazione. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Utilizzare lo strumento generatore di applicazioni, `express-generator`, per creare rapidamente uno scheletro di applicazione. + +È possibile eseguire il generatore di applicazioni con il comando `npx` (disponibile in Node.js 8.2.0). + +```bash +$ npx express-generator +``` + +Per le versioni precedenti di Node, installare il generatore di applicazioni come pacchetto globale npm e quindi lanciarlo: + +```bash +$ npm install -g express-generator +$ express +``` + +Visualizza le opzioni del comando con l'opzione `-h`: + +```bash +$ express -h + + Uso: express [options] [dir] + + Opzioni: + + -h, --help informazioni di utilizzo dell'output + --version output il numero di versione + -e, --ejs aggiungi il supporto del motore ejs + --hbs aggiungi il supporto del motore del manubrio + --pug aggiungi il supporto del motore del pug + -H, --hogan aggiungi hogan. s supporto motore + --no-view genera senza motore di visualizzazione + -v, --view aggiungi vista supporto (ejs hbs hjs jade pug twig vash) (valori predefiniti per jade) + -c, --css aggiungi il foglio di stile supporto (less stylus compass sass) (valori predefiniti per css normali) + --git add . itignore + -f, --force force sulla directory non vuota +``` + +Ad esempio, il seguente crea un'app Express chiamata *myapp*. L'app verrà creata in una cartella chiamata *myapp* nella directory di lavoro corrente e il motore di visualizzazione sarà impostato su Pug: + +```bash +$ express --view=pug myapp + + create : myapp + create : myapp/package.json + create : myapp/app. s + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/route + create : myapp/routes/index. s + create : myapp/routes/users. s + create : myapp/public/stylesheets + create : myapp/public/stylesheets/style. ss + create : myapp/views + create : myapp/views/index. ug + create : myapp/views/layout.pug + create : myapp/views/error. ug + create : myapp/bin + create : myapp/bin/www +``` + +Quindi installare dipendenze: + +```bash +$ cd myapp +$ npm install +``` + +Su MacOS o Linux, esegui l'app con questo comando: + +```bash +$ DEBUG=myapp:* npm start +``` + +Su Windows Command Prompt, utilizzare questo comando: + +```bash +> imposta DEBUG=myapp:* & npm start +``` + +Su Windows PowerShell, utilizzare questo comando: + +```bash +PS> $env:DEBUG='myapp:*'; npm start +``` + +Quindi, caricare `http://localhost:3000/` nel tuo browser per accedere all'app. + +L'app generata ha la seguente struttura di directory: + +```bash +. +├── app.js +├── bin +│ └── www +├── package.json +├── public +│ ├── images +│ ├── javascripts +│ └── stylesheets +│ └── style.css +├── routes +│ ├── index.js +│ └── users.js +└── views + ├── error.pug + ├── index.pug + └── layout.pug + +7 directories, 9 files +``` + + + +La struttura delle app creata dal generatore è solo uno dei tanti modi per strutturare le app Express. +Sentitevi liberi di utilizzare questa struttura o modificarla per soddisfare al meglio le vostre esigenze. + + diff --git a/src/content/docs/it/4x/starter/hello-world.mdx b/src/content/docs/it/4x/starter/hello-world.mdx new file mode 100644 index 0000000000..ebb1cf18e4 --- /dev/null +++ b/src/content/docs/it/4x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Ciao esempio mondiale +description: Inizia con Express.js costruendo una semplice applicazione 'Ciao Mondo', dimostrando la configurazione di base e la creazione di server per i principianti. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Incorporato qui sotto è essenzialmente l'app Express più semplice che puoi creare. Si tratta di un singolo file app +— *non* quello che si otterrebbe se si utilizza il [Express generator](/en/starter/generator), che +crea il ponteggio per un'app completa con numerosi file JavaScript, modelli Jade e sottodirectory +per vari scopi. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res. end('Hello World!'); +}); + +app.listen(port, () => { + console.log(`Example app listening on port ${port}`); +}); +``` + +Questa app avvia un server e ascolta la porta 3000 per le connessioni. L'app risponde con "Ciao Mondo!" per le richieste +all'URL radice (`/`) o *route*. Per ogni altro percorso, risponderà con un **404 non trovato**. + +## Esecuzione Localmente + +Crea prima una directory chiamata `myapp`, cambiala ed esegui `npm init`. Quindi, installa `express` come dipendenza, secondo la [guida all'installazione](/en/starter/installing). + +Nella directory `myapp`, crea un file chiamato `app.js` e copia il codice dall'esempio qui sopra. + + + +The `req` (request) and `res` (response) are the exact same objects that Node provides, so you can +invoke `req.pipe()`, `req.on('data', callback)`, and anything else you would do without Express +involved. + + + +Eseguire l'app con il seguente comando: + +```bash +$ node app.js +``` + +Quindi, caricare `http://localhost:3000/` in un browser per vedere l'output. diff --git a/src/content/docs/it/4x/starter/installing.mdx b/src/content/docs/it/4x/starter/installing.mdx new file mode 100644 index 0000000000..ef69cf7a33 --- /dev/null +++ b/src/content/docs/it/4x/starter/installing.mdx @@ -0,0 +1,50 @@ +--- +title: Installazione +description: Scopri come installare Express.js nel tuo ambiente Node.js, inclusa la creazione della directory del progetto e la gestione delle dipendenze con npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Prima di iniziare, assicurati di avere [Node.js](https://nodejs.org/) 0.10 o superiore installato. Quindi, creare una directory per la vostra applicazione e navigare in essa. + +```bash +mkdir myapp +cd myapp +``` + +Usa il comando `npm init` per creare un file `package.json` per la tua applicazione. +Per maggiori informazioni sul funzionamento di `package.json`, vedere [Specifiche della gestione di npm.json](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +Questo comando ti richiede un certo numero di cose, come il nome e la versione della tua applicazione. +Per ora, puoi semplicemente premere RETURN per accettare i valori predefiniti per la maggior parte di essi, con la seguente eccezione: + +``` +punto di ingresso: (index.js) +``` + +Inserisci `app.js`, o qualsiasi cosa desideri che sia il nome del file principale. Se vuoi che sia `index.js`, premi RETURN per accettare il nome del file predefinito suggerito. + +Ora, installa Express nella directory `myapp` e salvalo nella lista delle dipendenze. Per esempio: + +```bash +npm install express +``` + +Per installare Express temporaneamente e non aggiungerlo alla lista delle dipendenze: + +```bash +npm installa express --no-save +``` + + + +By default with version npm 5.0+, `npm install` adds the module to the `dependencies` list in the +`package.json` file; with earlier versions of npm, you must specify the `--save` option +explicitly. Poi, dopo aver eseguito `npm install` nella directory dell'app installerà automaticamente i moduli +nell'elenco delle dipendenze. + + diff --git a/src/content/docs/it/4x/starter/static-files.mdx b/src/content/docs/it/4x/starter/static-files.mdx new file mode 100644 index 0000000000..89d90034cf --- /dev/null +++ b/src/content/docs/it/4x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Servire file statici in Express +description: Comprendi come servire file statici come immagini, CSS e JavaScript nelle applicazioni Express.js utilizzando il middleware 'static' integrato. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Per servire file statici come immagini, file CSS e file JavaScript, utilizzare la funzione middleware integrata `express.static` in Express. + +La firma della funzione è: + +```js +express.static(root, [options]); +``` + +L'argomento `root` specifica la directory radice da cui servire le risorse statiche. +Per ulteriori informazioni sull'argomento `options`, vedere [express.static](/en/5x/api#express.static). + +Per esempio, utilizzare il seguente codice per servire immagini, file CSS e file JavaScript in una directory chiamata `public`: + +```js +app.use(express.static('public')); +``` + +Ora, puoi caricare i file che sono nella directory `public`: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express cerca i file relativi alla directory statica, quindi il nome della directory statica +non fa parte dell'URL. + + + +Per utilizzare più directory di asset statici, chiama la funzione middleware `express.static`: + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express cerca i file nell'ordine in cui si impostano le directory statiche con la funzione middleware `express.static`. + + + +Per ottenere risultati ottimali, utilizza un proxy +inverso cache per migliorare le prestazioni di +che servono risorse statiche. + + + +Per creare un prefisso di percorso virtuale (dove il percorso non esiste effettivamente nel file system) per i file serviti dal `express. funzione tatic`, [specify a mount path](/en/5x/api#app.use) per la directory statica, come mostrato di seguito: + +```js +app.use('/static', express.static('public')); +``` + +Ora puoi caricare i file che sono nella directory `public` dal prefisso del percorso `/static`. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +Tuttavia, il percorso che fornisci alla funzione `express.static` è relativo alla directory da cui avvii il processo `node`. Se si esegue l'app express da un'altra directory, è più sicuro utilizzare il percorso assoluto della directory che si desidera servire: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public')); +``` + +Per maggiori dettagli sulla funzione `serve-static` e sulle sue opzioni, vedere [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/it/5x/advanced/developing-template-engines.md b/src/content/docs/it/5x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..3c00548d60 --- /dev/null +++ b/src/content/docs/it/5x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Sviluppo di modelli di motori per Express +description: Impara a sviluppare motori di template personalizzati per Express.js utilizzando app.engine(), con esempi sulla creazione e l'integrazione della tua logica di rendering dei modelli. +--- + +Usa il metodo `app.engine(ext, callback)` per creare il tuo modello di motore. `ext` si riferisce all'estensione del file, e `callback` è la funzione del motore del modello, che accetta i seguenti elementi come parametri: la posizione del file, l'oggetto opzioni, e la funzione di callback. + +Il seguente codice è un esempio di implementazione di un semplice modello di motore per il rendering dei file `.ntl`. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +La tua app sarà ora in grado di visualizzare i file `.ntl`. Crea un file chiamato `index.ntl` nella directory `views` con il seguente contenuto. + +```pug +#title# +#message# +``` + +Quindi, crea il seguente percorso nella tua app. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +Quando fai una richiesta alla home page, `index.ntl` sarà renderizzato come HTML. diff --git a/src/content/docs/it/5x/guide/behind-proxies.mdx b/src/content/docs/it/5x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..eeb3cb8160 --- /dev/null +++ b/src/content/docs/it/5x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Espresso dietro i proxy +description: Scopri come configurare le applicazioni Express.js per funzionare correttamente dietro i proxy inversi, anche utilizzando l'impostazione del proxy di trust per gestire gli indirizzi IP del client. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Quando si esegue un'app Express dietro un proxy inverso, alcune delle API Express possono restituire valori diversi da quelli previsti. Al fine di adeguarsi a questo, l'impostazione dell'applicazione `trust proxy` può essere utilizzata per esporre le informazioni fornite dal proxy inverso nelle API Express. Il problema più comune è l'espressione API che espone l'indirizzo IP del cliente può invece mostrare un indirizzo IP interno del proxy inverso. + + + +Durante la configurazione dell'impostazione `trust proxy`, è importante capire l'esatta configurazione del proxy inverso +. Dal momento che questa impostazione sarà i valori di fiducia forniti nella richiesta, è importante che +la combinazione dell'impostazione in Express corrisponda al funzionamento del proxy inverso. + + + +L'impostazione dell'applicazione `trust proxy` può essere impostata su uno dei valori elencati nella seguente tabella. + + + + + + + + + + + + + + + + + + Funzione + + +
TypeValue
Boolean +Se `true`, l'indirizzo IP del cliente è inteso come la voce più sinistra nell'intestazione `X-Forwarded-For`. + +Se `false`, l'app è intesa come rivolta direttamente al client e l'indirizzo IP del cliente è derivato da `req.socket.remoteAddress`. Questa è l'impostazione predefinita. + + +Quando si imposta a `true`, è importante assicurarsi che l'ultimo proxy inverso attendibile stia rimuovendo/sovrascrivendo tutte le seguenti intestazioni HTTP: `X-Forwarded-For`, `X-Forwarded-Host`, e `X-Forwarded-Proto`, altrimenti potrebbe essere possibile per il cliente fornire qualsiasi valore. + +
indirizzi IP +Un indirizzo IP, una sottorete, o un array di indirizzi IP e sottoreti a cui fidarsi come proxy inverso. Il seguente elenco mostra i nomi pre-configurati delle sottorete + +* loopback - `127.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +È possibile impostare gli indirizzi IP in uno dei seguenti modi: + +```js +app.set('trust proxy', 'loopback'); // specify a single subnet +app.set('trust proxy', 'loopback, 123.123.123.123'); // specify a subnet and an address +app.set('trust proxy', 'loopback, linklocal, uniquelocal'); // specify multiple subnets as CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // specify multiple subnets as an array +``` + +Se specificato, gli indirizzi IP o le sottoreti sono esclusi dal processo di determinazione dell'indirizzo, e l'indirizzo IP non attendibile più vicino al server dell'applicazione è determinato come indirizzo IP del client. Questo funziona controllando se `req.socket.remoteAddress` è attendibile. In tal caso, ogni indirizzo in `X-Forwarded-For` viene controllato da destra a sinistra fino al primo indirizzo non fidato. + +
Numero +Usa l'indirizzo che è al massimo `n` numero di luppolo lontano dall'applicazione Express. `req.socket.remoteAddress` è il primo hop, e il resto sono cercati nell'intestazione `X-Forwarded-For` da destra a sinistra. Un valore di `0` significa che il primo indirizzo non attendibile sarebbe `req.socket.remoteAddress`, cioè non c'è un proxy inverso. + + +Quando si utilizza questa impostazione, è importante assicurarsi che non ci siano multipli, percorsi diversi per l'applicazione Express in modo che il client possa essere inferiore al numero configurato di luppolo di distanza, altrimenti potrebbe essere possibile per il cliente fornire qualsiasi valore. + +
+ +Implementazione fiducia personalizzata. + +```js +app.set('trust proxy', (ip) => { + if (ip === '127.0.0.1' ip === '123.123.123. 23') + return true; // trusted IPs + else return false; +}); +``` + +
+ +Abilitare il `trust proxy` avrà il seguente impatto: + +
    +
  • + Il valore di [req.hostname](/en/api#req.hostname) è derivato dal valore impostato nell'intestazione + `X-Forwarded-Host`, che può essere impostato dal cliente o dal proxy. +
    • +
  • + `X-Forwarded-Proto` può essere impostato dal proxy inverso per dire all'app se si tratta di `↓ ` o + `http` o anche di un nome non valido. Questo valore è riflesso da [req.protocol](/en/api#req.protocol). +
    • +
  • + I valori [req.ip](/en/api#req.ip) e [req.ips](/en/api#req.ips) sono popolati in base all'indirizzo del socket + e all'intestazione `X-Forwarded-For`, a partire dal primo indirizzo non fidato. +
    • +
+ +L'impostazione `trust proxy` è implementata usando il pacchetto [proxy-addr](https://www.npmjs.com/package/proxy-addr). Per ulteriori informazioni, consultare la documentazione. diff --git a/src/content/docs/it/5x/guide/debugging.mdx b/src/content/docs/it/5x/guide/debugging.mdx new file mode 100644 index 0000000000..592e46618a --- /dev/null +++ b/src/content/docs/it/5x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Debug Express +description: Scopri come abilitare e utilizzare i log di debug nelle applicazioni Express.js impostando la variabile di ambiente DEBUG per la risoluzione dei problemi migliorata. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Per vedere tutti i log interni utilizzati in Express, imposta la variabile d'ambiente `DEBUG` su +`express:*` quando lancia la tua app. + +```bash +$ DEBUG=express:* node index.js +``` + +Su Windows, utilizzare il comando corrispondente. + +```bash +> $env:DEBUG = "express:*"; node index.js +``` + +L'esecuzione di questo comando nell'app predefinita generata dal [express generator](/en/starter/generator) stampa il seguente output: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +Quando viene fatta una richiesta all'applicazione, vedrete i registri specificati nel codice Express: + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index.pug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +Per vedere i log solo dall'implementazione del router, imposta il valore di `DEBUG` su `express:router`. Allo stesso modo, per vedere i log solo dall'implementazione dell'applicazione, imposta il valore di `DEBUG` su `express:application`, e così via. + +## Applicazioni generate da `express` + +Un'applicazione generata dal comando `express` utilizza il modulo `debug` e il suo namespace di debug è indirizzato al nome dell'applicazione. + +Ad esempio, se hai generato l'app con `$ express sample-app`, puoi abilitare le istruzioni di debug con il seguente comando: + +```bash +$ DEBUG=sample-app:* node ./bin/www +``` + +È possibile specificare più di uno spazio dei nomi di debug assegnando una lista di nomi separati da virgole: + +```bash +$ DEBUG=http,mail,express:* node index.js +``` + +## Opzioni avanzate + +Quando si esegue attraverso Node.js, è possibile impostare alcune variabili di ambiente che cambieranno il comportamento della registrazione di debug: + +| Nome | Scopo | +| ------------------- | ------------------------------------------------------- | +| `DEBUG` | Abilita/disabilita spazi di debug specifici. | +| `DEBUG_COLORS` | Indica se usare o meno i colori nell'output di debug. | +| `DEBUG_DEPTH` | Profondità dell'ispezione dell'oggetto. | +| `DEBUG_FD` | Descrittore file su cui scrivere l'output di debug. | +| `DEBUG_SHOW_HIDDEN` | Mostra le proprietà nascoste sugli oggetti ispezionati. | + + + +Le variabili di ambiente che iniziano con `DEBUG_` finiscono per essere convertite in un oggetto Opzioni +che viene utilizzato con i formatori `%o`/`%O`. Vedere la documentazione Node.js per +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) per l'elenco completo +. + + diff --git a/src/content/docs/it/5x/guide/error-handling.mdx b/src/content/docs/it/5x/guide/error-handling.mdx new file mode 100644 index 0000000000..affc346d07 --- /dev/null +++ b/src/content/docs/it/5x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Gestione Degli Errori +description: Capire come Express.js gestisce gli errori nel codice sincrono e asincrono e imparare ad implementare middleware gestione degli errori personalizzati per le vostre applicazioni. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Error Handling* si riferisce a come Express cattura ed elabora gli errori +che si verificano in modo sincrono e asincrono. Express viene fornito con un gestore di errore +predefinito quindi non è necessario scrivere il proprio per iniziare. + +## Errori Di Cattura + +È importante garantire che Express colmi tutti gli errori che si verificano mentre +gestisce le rotte e middleware. + +Gli errori che si verificano nel codice sincrono all'interno dei gestori del percorso e del middleware +non richiedono lavoro aggiuntivo. Se il codice sincrono lancia un errore, allora Express catturerà +ed elaborerà esso. Per esempio: + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Express lo catturerà da solo. +}); +``` + +Per gli errori restituiti da funzioni asincrone invocate dai gestori degli itinerari +e middleware, devi passarli alla funzione `next()`, dove Express sarà +catturarli ed elaborarli. Per esempio: + +```js +app.get('/', (req, res, next) => { + fs. eadFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Passa gli errori a Express. + } else { + res. end(dati); + } + }); +}); +``` + +A partire da Express 5, i gestori del percorso e il middleware che restituiscono una Promise +chiameranno automaticamente `next(value)` quando rifiutano o generano un errore. +Per esempio: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = await getUserById(req.params.id); + res.send(user); +}); +``` + +Se `getUserById` genera un errore o rifiuta, `next` verrà chiamato con +l'errore generato o il valore rifiutato. Se non viene fornito alcun valore rifiutato, `next` +verrà chiamato con un oggetto di errore predefinito fornito dal router Express. + +Se passi qualcosa alla funzione `next()` (tranne la stringa `'route'`), +Express considera la richiesta corrente come un errore e salterà qualsiasi +rimanenti funzioni di routing e middleware senza errori. + +Se il callback in una sequenza non fornisce dati, solo errori, è possibile semplificare +questo codice come segue: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +Nell'esempio precedente, `next` è fornito come callback per `fs.writeFile`, +che viene chiamato con o senza errori. Se non c'è errore, viene eseguito il secondo gestore +, altrimenti Express cattura ed elabora l'errore. + +È necessario catturare gli errori che si verificano in codice asincrono invocato dai router o +middleware e passarli a Express per l'elaborazione. Per esempio: + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + next(err); + } + }, 100); +}); +``` + +L'esempio precedente utilizza un blocco `try...catch` per catturare errori nel codice asincrono +e passarli a Express. Se il blocco `prova...catch` +fosse omesso, Express non coglierebbe l'errore dal momento che non fa parte del codice di gestione +sincrono. + +Usa le promesse per evitare l'overhead del blocco `prova...catch` o quando usi le funzioni +che restituiscono le promesse. Per esempio: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + . hen(() => { + throw new Error('BROKEN'); + }) + . atch(next); // Gli errori saranno passati a Express. +}); +``` + +Dal momento che le promesse catturano automaticamente entrambi gli errori sincroni e le promesse rifiutate, +puoi semplicemente fornire `next` come il gestore finale di cattura e Express catturerà errori, +perché al gestore della cattura viene dato l'errore come primo argomento. + +Si potrebbe anche utilizzare una catena di gestori per fare affidamento su errore sincrono +catching, riducendo il codice asincrono a qualcosa di banale. Per esempio: + +```js +app.get('/', [ + function (req, res, next) { + fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals. ata = dati; + next(err); + }); + }, + function (req, res) { + res. ocals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +L'esempio precedente ha un paio di istruzioni banali dalla chiamata `readFile` +. Se `readFile` causa un errore, allora passa l'errore a Express, altrimenti +torna rapidamente al mondo della gestione sincrona degli errori nel prossimo gestore +nella catena. Poi, l'esempio di cui sopra cerca di elaborare i dati. Se questo fallisce, il gestore di errori sincroni +lo catturerà. Se avessi fatto questa elaborazione all'interno di +il callback `readFile`, l'applicazione potrebbe uscire e i gestori dell'errore Express +non sarebbero stati eseguiti. + +Qualunque metodo si utilizzi, se si desidera che i gestori di errori Express siano chiamati dentro e l'applicazione +per sopravvivere, è necessario assicurarsi che Express riceva l'errore. + +## Il gestore degli errori predefinito + +Express è dotato di un gestore di errori integrato che si occupa di eventuali errori che potrebbero essere riscontrati nell'app. Questa funzione middleware di gestione degli errori predefinita viene aggiunta alla fine dello stack della funzione middleware. + +Se passi un errore a `next()` e non lo gestisci in un gestore di errore +personalizzato, sarà gestito dal gestore di errori integrato; l'errore sarà +scritto al client con la traccia dello stack. La traccia dello stack non è inclusa +nell'ambiente di produzione. + + + +Imposta la variabile d'ambiente `NODE_ENV` su `production`, per eseguire l'applicazione in modalità di produzione. + + + +Quando viene scritto un errore, alla risposta +vengono aggiunte le seguenti informazioni: + +* Il `res.statusCode` è impostato da `err.status` (o `err.statusCode`). Se + questo valore è al di fuori dell'intervallo 4xx o 5xx, sarà impostato a 500. +* Il `res.statusMessage` è impostato in base al codice di stato. +* Il corpo sarà l'HTML del messaggio del codice di stato quando in ambiente di produzione + , altrimenti sarà `err.stack`. +* Qualsiasi intestazione specificata in un oggetto `err.headers`. + +Se chiami `next()` con un errore dopo aver iniziato a scrivere la risposta +(ad esempio, se riscontri un errore durante lo streaming della risposta +al client), il gestore di errore predefinito Express chiude la connessione +e non riesce la richiesta. + +Quindi, quando si aggiunge un gestore di errori personalizzato, è necessario delegare a +il gestore di errori Express predefinito, quando le intestazioni +sono già state inviate al client: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Nota che il gestore di errori predefinito può essere attivato se chiami `next()` con un errore +nel tuo codice più di una volta, anche se la gestione degli errori personalizzati è in funzione. + +Altri errori di gestione middleware possono essere trovati su [Express middleware](/en/resources/middleware). + +## Gestione errori di scrittura + +Definire le funzioni middleware per la gestione degli errori allo stesso modo di altre funzioni middleware, +eccetto le funzioni di gestione degli errori hanno quattro argomenti invece di tre: +`(err, req, res, next)`. Per esempio: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Definisci l'ultima gestione degli errori del middleware, dopo altre chiamate `app.use()` e percorsi; per esempio: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser. rlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app. se(methodOverride()); +app.use((err, req, res, next) => { + // logic +}); +``` + +Le risposte da all'interno di una funzione middleware possono essere in qualsiasi formato, come una pagina di errore HTML, un semplice messaggio, o una stringa JSON. + +Per scopi organizzativi (e di framework di livello superiore) è possibile definire diverse funzioni middleware di gestione degli errori +come si farebbe con funzioni di middleware regolari +. Ad esempio, per definire un gestore di errori +per le richieste fatte utilizzando `XHR` e quelle senza: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app. se( + bodyParser.urlencoded({ + extended true, + }) +); +app. se(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +In questo esempio, i `logErrors` generici potrebbero scrivere la richiesta e le informazioni di errore +in `stderr`, per esempio: + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +Anche in questo esempio, `clientErrorHandler` è definito come segue; in questo caso, l'errore viene esplicitamente passato a quello successivo. + +Nota che quando *non* chiama "next" in una funzione di gestione degli errori, sei responsabile della scrittura (e della fine) della risposta. In caso contrario, tali richieste saranno "appese" e non saranno ammissibili per la raccolta rifiuti. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500). end({ error: 'Something failed!' }); + } else { + next(err); + } +} +``` + +Implementa la funzione `errorHandler` "catch-all" come segue (per esempio): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +Se si dispone di un gestore del percorso con molteplici funzioni di callback, è possibile utilizzare il parametro `route` per passare al prossimo gestore del percorso. Per esempio: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user. asPaid) { + // continue handling this request + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent. ind((err, doc) => { + if (err) return next(err); + res. son(doc); + }); + } +); +``` + +In questo esempio, il gestore `getPaidContent` sarà saltato, ma qualsiasi gestore rimanente in `app` per `/a_route_behind_paywall` continuerà ad essere eseguito. + + + +Le chiamate a `next()` e `next(err)` indicano che il gestore corrente è completo e in quale stato. +`next(err)` salterà tutti i gestori rimanenti nella catena ad eccezione di quelli che sono impostati su +gestire gli errori come descritto sopra. + + diff --git a/src/content/docs/it/5x/guide/overriding-express-api.md b/src/content/docs/it/5x/guide/overriding-express-api.md new file mode 100644 index 0000000000..86696c08e0 --- /dev/null +++ b/src/content/docs/it/5x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Sovrascrivendo l'API Express +description: Scopri come personalizzare ed estendere l'API di Express.js sovrascrivendo i metodi e le proprietà su richiesta e gli oggetti di risposta utilizzando prototipi. +--- + +L'API Express è composta da vari metodi e proprietà su richiesta e oggetti di risposta. Questi sono ereditati dal prototipo. Ci sono due punti di estensione per l'API Express: + +1. I prototipi globali in `express.request` e `express.response`. +2. prototipi specifici per app su `app.request` e `app.response`. + +La modifica dei prototipi globali influenzerà tutte le applicazioni Express caricate nello stesso processo. Se lo si desidera, le modifiche possono essere rese specifiche alle app modificando solo i prototipi specifici delle app dopo aver creato una nuova app. + +## Metodi + +È possibile sovrascrivere la firma e il comportamento dei metodi esistenti con il proprio, assegnando una funzione personalizzata. + +Di seguito è riportato un esempio di sovrascrittura del comportamento di [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +L'implementazione di cui sopra cambia completamente la firma originale di `res.sendStatus`. Ora accetta un codice di stato, il tipo di codifica e il messaggio da inviare al client. + +Il metodo overridden può ora essere utilizzato in questo modo: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## Proprietà + +Le proprietà nell'API Express sono: + +1. Proprietà assegnate (es: `req.baseUrl`, `req.originalUrl`) +2. Definito come getters (es: `req.secure`, `req.ip`) + +Poiché le proprietà sotto la categoria 1 sono assegnate dinamicamente sugli oggetti `request` e `response` nel contesto dell'attuale ciclo di richiesta-risposta, il loro comportamento non può essere superato. + +Le proprietà sotto la categoria 2 possono essere sovrascritte utilizzando le API di estensione Express. + +Il seguente codice riscrive come deve essere derivato il valore di `req.ip`. Ora restituisce semplicemente il valore dell'intestazione della richiesta `Client-IP`. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Protototipo + +Al fine di fornire l'API Express, gli oggetti richiesta/risposta passati a Express (tramite `app(req, res)`, per esempio) bisogno di ereditare dalla stessa catena prototipo. Per impostazione predefinita, questo è `http.IncomingRequest.prototype` per la richiesta e `http.ServerResponse.prototype` per la risposta. + +Se non necessario, si raccomanda che ciò avvenga solo a livello di applicazione e non a livello globale. Inoltre, fare in modo che il prototipo che viene utilizzato corrisponda la funzionalità il più vicino possibile ai prototipi predefiniti. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/it/5x/guide/routing.mdx b/src/content/docs/it/5x/guide/routing.mdx new file mode 100644 index 0000000000..4a65c235d4 --- /dev/null +++ b/src/content/docs/it/5x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Routing +description: Scopri come definire e utilizzare i percorsi nelle applicazioni Express.js, inclusi i metodi di percorso, i percorsi e i parametri e utilizzando Router per il routing modulare. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* si riferisce a come gli endpoint di un'applicazione (URI) rispondono alle richieste del client. +Per un'introduzione al routing, vedere [Instradamento di base](/en/starter/basic-routing). + +Definisci il routing usando metodi dell'oggetto `app` Express che corrispondono ai metodi HTTP; +per esempio, `app. et()` per gestire le richieste GET e `app.post` per gestire le richieste POST. Per una lista completa, +vedi [app.METHOD](/en/5x/api#app.METHOD). Puoi anche usare [app.all()](/en/5x/api#app.all) per gestire tutti i metodi HTTP e [app. se()](/en/5x/api#app.use) to +specify middleware as the callback function (Vedi [Using middleware](/en/guide/using-middleware) for details). + +Questi metodi di routing specificano una funzione di callback (a volte chiamata "funzioni di handler") chiamata quando l'applicazione riceve una richiesta al percorso specificato (endpoint) e il metodo HTTP. In altre parole, l'applicazione "ascolta" per le richieste che corrispondono ai percorsi e ai metodi specificati, e quando rileva una corrispondenza, chiama la funzione di callback specificata. + +Infatti, i metodi di routing possono avere più di una funzione di callback come argomenti. +Con funzioni di callback multiple, è importante fornire `next` come argomento alla funzione di callback e poi chiamare `next()` all'interno del corpo della funzione per consegnare il controllo +al prossimo callback. + +Il seguente codice è un esempio di un percorso molto basilare. + +```js +const express = require('express'); +const app = express(); + +// rispondi con "ciao mondo" quando una richiesta GET viene fatta all'app homepage +. et('/', (req, res) => { + res.send('hello world'); +}); +``` + +## Metodi percorso + +Un metodo di percorso è derivato da uno dei metodi HTTP ed è collegato ad un'istanza della classe `express`. + +Il seguente codice è un esempio di percorsi definiti per il `GET` e i metodi `POST` nella root dell'app. + +```js +// GET method route +app.get('/', (req, res) => { + res. end('Richiesta GET alla homepage'); +}); + +// POST metodo percorso +app. ost('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Express supporta metodi che corrispondono a tutti i metodi di richiesta HTTP: `get`, `post`, e così via. +Per un elenco completo, vedere [app.METHOD](/en/5x/api#app.METHOD). + +C'è un metodo di routing speciale, `app.all()`, utilizzato per caricare le funzioni middleware in un percorso per *tutti* i metodi di richiesta HTTP. Ad esempio, il seguente gestore viene eseguito per le richieste al percorso `"/secret"` se si utilizza `GET`, `POST`, `PUT`, `DELETE`, o qualsiasi altro metodo di richiesta HTTP supportato nel [modulo http](https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Accedere alla sezione segreta ...'); + next(); // passare il controllo al prossimo gestore +}); +``` + +## Percorsi di rotta + +Percorsi di percorso, in combinazione con un metodo di richiesta, definire gli endpoint in cui le richieste possono essere fatte. I tracciati del percorso possono essere stringhe, motivi di stringa o espressioni regolari. + + + +In express 5, i personaggi `? , `+`, `\*`, `[]`, e `()\` sono gestiti in modo diverso rispetto alla versione +4, si prega di rivedere la [guida alla migrazione](/en/guide/migrating-5#path-syntax) per maggiori informazioni. + + + + + +Nell'espressione 4, i caratteri di espressione regolare come `$` devono essere fuggiti con un `\`. + + + + + +Express utilizza [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) per abbinare i percorsi del percorso +; vedere la documentazione path-to-regexp per tutte le possibilità di definire i percorsi del percorso. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) è uno strumento utile per +testare i percorsi Express di base, anche se non supporta la corrispondenza dei modelli. + + + +Le stringhe di query non fanno parte del percorso percorso. + +### Percorsi di percorso basati su stringhe + +Questo percorso corrisponderà alle richieste del percorso root, `/`. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +Questo percorso corrisponderà alle richieste di `/about`. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +Questo percorso corrisponderà alle richieste a `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Percorsi del percorso in base ai motivi delle stringhe + + + +I modelli di stringhe in Express 5 non funzionano più. Si prega di fare riferimento alla [guida di migrazione +(/en/guide/migrating-5#path-syntax) per ulteriori informazioni. + + + +Questo percorso corrisponde a `acd` e `abcd`. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +Questo percorso corrisponderà a `abcd`, `abbcd`, `abbbcd`, e così via. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +Questo percorso corrisponde a `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd`, e così via. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +Questo percorso corrisponde a `/abe` e `/abcde`. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Percorsi di percorso basati su espressioni regolari + +Questo percorso corrisponderà a qualsiasi cosa con una "a" in esso. + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +Questo percorso corrisponde a `butterfly` e `dragonfly`, ma non a `butterflyman`, `dragonflyman`, e così via. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Parametri percorso + +I parametri del percorso sono denominati segmenti di URL che vengono utilizzati per catturare i valori specificati nella loro posizione nell'URL. I valori catturati sono popolati nell'oggetto `req.params`, con il nome del parametro route specificato nel percorso come loro rispettive chiavi. + +``` +Percorso del percorso: /users/:userId/books/:bookId +Richiedi URL: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +Per definire i percorsi con i parametri del percorso, è sufficiente specificare i parametri del percorso nel percorso come mostrato di seguito. + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +Il nome dei parametri del percorso deve essere composto da "caratteri di parola" ([A-Za-z0-9_]). + + + +Poiché il trattino (`-`) e il punto (`.`) sono interpretati letteralmente, possono essere utilizzati insieme ai parametri del percorso per scopi utili. + +``` +Percorso del percorso: /flights/:from-:to +Richiedi URL: http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Percorso percorso: /plantae/:genus.:species +Richiedi URL: http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +In express 5, Regexp characters are not supported in route paths, for more information please +refer to the [migration guide](/en/guide/migrating-5#path-syntax). + + + +Per avere più controllo sulla stringa esatta che può essere abbinata a un parametro del percorso, puoi aggiungere un'espressione regolare tra parentesi (`()`): + +``` +Percorso del percorso: /user/:userId(\d+) +Richiedi URL: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Perché l'espressione regolare è di solito parte di una stringa letterale, assicurati di sfuggire a qualsiasi carattere `\` +con un backslash aggiuntivo, ad esempio `\d+`. + + + + +In Express 4.x, il carattere `*` nelle espressioni regolari non viene interpretato nel modo usuale. Come soluzione puoi usare `{0,}` invece di `*`. Questo sarà probabilmente fissato in Express 5. + + +## Gestori del percorso + +È possibile fornire più funzioni di callback che si comportano come [middleware](/en/guide/using-middleware) per gestire una richiesta. L'unica eccezione è che questi callback potrebbero invocare `next('route')` per bypassare i rimanenti callback del percorso. È possibile utilizzare questo meccanismo per imporre condizioni preliminari su un percorso, poi passare il controllo ai percorsi successivi se non c'è motivo di procedere con il percorso corrente. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params. d === '0') { + return next('route'); + } + res. end(`User ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Special handler for user ID 0'); +}); +``` + +In questo esempio: + +* `GET /user/5` → gestito dal primo percorso → invia "User 5" +* `GET /user/0` → prima rotta chiama `next('route')`, saltando al prossimo percorso corrispondente `/user/:id` + +I gestori del percorso possono essere nella forma di una funzione, una serie di funzioni, o combinazioni di entrambi, come mostrato negli esempi seguenti. + +Una singola funzione di callback può gestire un percorso. Per esempio: + +```js +app.get('/example/a', (req, res) => { + res.send('Hello from A!'); +}); +``` + +Più di una funzione di callback può gestire un percorso (assicurati di specificare l'oggetto `next`). Per esempio: + +```js +app.get( + '/example/b', + (req, res, next) => { + console. og('la risposta verrà inviata dalla funzione successiva . .'); + next(); + }, + (req, res) => { + res. end('Ciao da B!'); + } +); +``` + +Un array di funzioni di callback può gestire un percorso. Per esempio: + +```js +const cb0 = function (req, res, next) { + console. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +const cb2 = function (req, res) { + res. end('Ciao da C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +Una combinazione di funzioni indipendenti e matrici di funzioni può gestire un percorso. Per esempio: + +```js +const cb0 = function (req, res, next) { + console. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +app. et( + '/example/d', + [cb0, cb1], + (req, res, next) => { + console. og('la risposta verrà inviata dalla funzione successiva . .'); + next(); + }, + (req, res) => { + res. end('Ciao da D!'); + } +); +``` + +## Metodi di risposta + +I metodi sull'oggetto di risposta (`res`) nella tabella seguente possono inviare una risposta al client e terminare il ciclo di richiesta-risposta. Se nessuno di questi metodi è chiamato da un gestore del percorso, la richiesta del cliente sarà sospesa. + +| Metodo | Descrizione | +| --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | +| [res.download()](/en/5x/api#res.download) | Avverte un file da scaricare. | +| [res.end()](/en/5x/api#res.end) | Termina il processo di risposta. | +| [res.json()](/en/5x/api#res.json) | Invia una risposta JSON. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Invia una risposta JSON con il supporto JSONP. | +| [res.redirect()](/en/5x/api#res.redirect) | Reindirizza una richiesta. | +| [res.render()](/en/5x/api#res.render) | Render un modello di visualizzazione. | +| [res.send()](/en/5x/api#res.send) | Invia una risposta di vari tipi. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Invia un file come un flusso di otte. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Imposta il codice di stato della risposta e invia la sua rappresentazione della stringa come corpo della risposta. | + +## app.route() + +È possibile creare i gestori di rotte per un percorso utilizzando `app.route()`. +Poiché il percorso è specificato in una singola posizione, è utile creare percorsi modulari, così come ridurre la ridondanza e pneumatici. Per ulteriori informazioni sulle rotte, si veda: [Router() documentation](/en/5x/api#router). + +Ecco un esempio di router incatenati che sono definiti utilizzando `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res. end('Ottieni un libro casuale'); + }) + . ost((req, res) => { + res.send('Add a book'); + }) + . ut((req, res) => { + res.send('Aggiorna il libro'); +}); +``` + +## express.Router + +Usa la classe `express.Router` per creare i gestori modulari e montabili. Un'istanza `Router` è un sistema di routing e middleware completo; per questo motivo è spesso chiamata "mini-app". + +L'esempio seguente crea un router come modulo, carica una funzione middleware in esso, definisce alcuni percorsi e monta il modulo del router su un percorso nell'app principale. + +Crea un file router chiamato `birds.js` nella directory delle app, con il seguente contenuto: + +```js +const express = require('express'); +const router = express. outer(); + +// middleware che è specifico per questo router +const timeLog = (req, res, next) => { + console. og('Orario: ', Date.now()); + next(); +}; +router. se(timeLog); + +// definisci il percorso della home page +router.get('/', (req, res) => { + res. end('Birds home page'); +}); +// definire il router sulla rotta +. et('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Quindi, caricare il modulo router nell'app: + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +L'app sarà ora in grado di gestire le richieste di `/birds` e `/birds/about`, oltre a chiamare la funzione middleware `timeLog` che è specifica per il percorso. + +Ma se il percorso principale `/birds` ha parametri di percorso, non sarà accessibile per impostazione predefinita dai sotto-percorsi. Per renderlo accessibile, dovrai passare l'opzione `mergeParams` al costruttore Router [reference](/en/5x/api#app.use). + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/it/5x/guide/using-middleware.mdx b/src/content/docs/it/5x/guide/using-middleware.mdx new file mode 100644 index 0000000000..d076967bee --- /dev/null +++ b/src/content/docs/it/5x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Usare middleware +description: Scopri come utilizzare middleware nelle applicazioni Express.js, tra cui middleware a livello di applicazione e router, gestione degli errori e integrazione di middleware di terze parti. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express è un framework web routing e middleware che ha funzionalità minime proprie: Un'applicazione Express è essenzialmente una serie di chiamate di funzioni middleware. + +Le funzioni *Middleware* sono funzioni che hanno accesso al [request object](/en/5x/api#req) (`req`), il [response object](/en/5x/api#res) (`res`), e la successiva funzione middleware nel ciclo request-response dell'applicazione. La funzione middleware successiva è comunemente indicata da una variabile chiamata `next`. + +Le funzioni Middleware possono eseguire le seguenti attività: + +* Esegue qualsiasi codice. +* Effettuare modifiche alla richiesta e agli oggetti di risposta. +* Terminare il ciclo richiesta-risposta. +* Chiama la funzione middleware successiva nello stack. + +Se la funzione middleware corrente non termina il ciclo richiesta-risposta, deve chiamare `next()` per passare il controllo alla successiva funzione middleware. In caso contrario, la richiesta sarà sospesa. + +Un'applicazione Express può utilizzare i seguenti tipi di middleware: + +* [Application-level middleware](#middleware.application) +* [Router-level middleware](#middleware.router) +* [Gestione errori middleware](#middleware.error-handling) +* [Built-in middleware](#middleware.built-in) +* [middleware di terze parti](#middleware.third-party) + +È possibile caricare il middleware a livello di applicazione e router con un percorso di montaggio opzionale. +È inoltre possibile caricare una serie di funzioni middleware insieme, che crea una sottopila del sistema middleware in un punto di montaggio. + +## Middleware a livello di applicazione + +Associa il middleware di livello applicativo ad un'istanza del [app object](/en/5x/api#app) usando `app.use()` e `app. ETHOD()` funzioni, dove `METHOD` è il metodo HTTP della richiesta che la funzione middleware gestisca (come GET, PUT, o POST) in minuscolo. + +Questo esempio mostra una funzione middleware senza percorso di montaggio. La funzione viene eseguita ogni volta che l'app riceve una richiesta. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +Questo esempio mostra una funzione middleware montata sul percorso `/user/:id`. La funzione viene eseguita per qualsiasi tipo di richiesta HTTP +sul percorso `/user/:id`. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +Questo esempio mostra un percorso e la sua funzione di gestore (sistema middleware). La funzione gestisce le richieste GET al percorso `/user/:id`. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +Ecco un esempio di caricamento di una serie di funzioni middleware in un punto di montaggio, con un percorso di montaggio. +Illustra un sub-stack middleware che stampa la richiesta di informazioni per qualsiasi tipo di richiesta HTTP al percorso `/user/:id`. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + console. og('Request Type:', req.method); + next(); + } +); +``` + +I gestori del percorso consentono di definire percorsi multipli per un percorso. L'esempio sottostante definisce due percorsi per le richieste GET al percorso `/user/:id`. Il secondo percorso non causerà alcun problema, ma non verrà mai chiamato perché il primo percorso termina il ciclo richiesta-risposta. + +Questo esempio mostra un sub-stack middleware che gestisce le richieste GET al percorso `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req. arams.id); + next(); + }, + (req, res, next) => { + res. end('Info utente'); + } +); + +// handler per il percorso /user/:id, che stampa l'app ID utente +. et('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +Per saltare il resto delle funzioni middleware da uno stack middleware router, chiama `next('route')` per passare il controllo al percorso successivo. + + + +`next('route')` will work only in middleware functions that were loaded by using the +`app.METHOD()` or `router.METHOD()` functions. + + + +Questo esempio mostra un sub-stack middleware che gestisce le richieste GET al percorso `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + // se l'ID utente è 0, salta al prossimo percorso + se (req. arams. d === '0') next('route'); + // altrimenti passa il controllo alla funzione middleware successiva in questo stack + altrimenti successivo(); + }, + (req, res, next) => { + // invia una risposta regolare + res. end('regular'); + } +); + +// handler per il percorso /user/:id, che invia una risposta speciale +app. et('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +Middleware può anche essere dichiarato in un array per la riutilizzabilità. + +Questo esempio mostra un array con un sub-stack middleware che gestisce le richieste GET al percorso `/user/:id` + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req. riginalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Request Type:', req. ethod); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app. et('/user/:id', logStuff, (req, res, next) => { + res.send('User Info'); +}); +``` + +## Router-level middleware + +Router-level middleware funziona allo stesso modo di application-level middleware, tranne che è legato ad un'istanza di `express.Router()`. + +```js +router const = express.Router(); +``` + +Carica il middleware a livello router usando le funzioni `router.use()` e `router.METHOD()`. + +Il seguente esempio di codice replica il sistema middleware che viene mostrato sopra per il middleware a livello di applicazione, utilizzando il middleware a livello di router: + +```js +const express = require('express'); +const app = express(); +const router = express. outer(); + +// una funzione middleware senza percorso di montaggio. Questo codice viene eseguito per ogni richiesta al router +. se((req, res, next) => { + console.log('Time:', Date. ow()); + next(); +}); + +// un sub-stack middleware mostra le informazioni di richiesta per qualsiasi tipo di richiesta HTTP al router /user/:id path +. se( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req. riginalUrl); + next(); + }, + (req, res, next) => { + console. og('Request Type:', req. ethod); + next(); + } +); + +// un sub-stack middleware che gestisce le richieste GET al router /user/:id path +. et( + '/user/:id', + (req, res, next) => { + // se l'ID utente è 0, salta al router successivo + se (req. arams. d === '0') next('route'); + // altrimenti passa il controllo alla successiva funzione middleware in questo stack + altrimenti successivo(); + }, + (req, successivo) => { + // renderizza una pagina normale + res. ender('regular'); + } +); + +// handler per il percorso /user/:id, che rende una pagina speciale +router. et('/user/:id', (req, res, next) => { + console. og(req.params.id); + res.render('special'); +}); + +// monta il router sull'app +app.use('/', router); +``` + +Per saltare il resto delle funzioni middleware del router, chiama `next('router')` +per passare il controllo indietro dall'istanza del router. + +Questo esempio mostra un sub-stack middleware che gestisce le richieste GET al percorso `/user/:id`. + +```js +const express = require('express'); +const app = express(); +const router = express. outer(); + +// predicare il router con un controllo e salvataggio quando necessario router +. se((req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router. et('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// usa il router e 401 qualsiasi cosa che cade attraverso l'app +. se('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## middleware gestione errori + + + +La gestione degli errori del middleware richiede sempre *four* argomenti. È necessario fornire quattro argomenti per +identificarlo come una funzione middleware di gestione degli errori. Anche se non è necessario utilizzare l'oggetto `next` +, è necessario specificarlo per mantenere la firma. Otherwise, the `next` object will be +interpreted as regular middleware and will fail to handle errors. + + + +Definire le funzioni middleware per la gestione degli errori allo stesso modo di altre funzioni middleware, tranne con quattro argomenti invece di tre, specificatamente con la firma `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Per maggiori dettagli sulla gestione degli errori middleware, vedere [Gestione degli errori](/en/guide/error-handling). + +## Middleware incorporato + +A partire dalla versione 4.x, Express non dipende più da [Connect](https://github.com/senchalabs/connect). Le funzioni middleware +che erano state precedentemente incluse con Express sono ora in moduli separati; vedi [la lista delle funzioni middleware](https://github.com/senchalabs/connect#middleware). + +Express ha le seguenti funzioni middleware integrate: + +* [express.static](/en/5x/api#express.static) serve risorse statiche come file HTML, immagini e così via. +* [express.json](/en/5x/api#express.json) analizza le richieste in arrivo con i payload JSON. **NOTA: Disponibile con Express 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) analizza le richieste in arrivo con payload codificati con URL. **NOTA: Disponibile con Express 4.16.0+** + +## middleware di terze parti + +Usa middleware di terze parti per aggiungere funzionalità alle app Express. + +Installare il modulo Node.js per le funzionalità richieste, quindi caricarlo nell'app a livello di applicazione o a livello di router. + +L'esempio seguente illustra l'installazione e il caricamento della funzione middleware di analisi dei cookie `cookie-parser`. + +```bash +$ npm install cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// load the cookie-parsing middleware +app.use(cookieParser()); +``` + +Per una lista parziale delle funzioni middleware di terze parti che sono comunemente usate con Express, vedere [middleware di terze parti](../resources/middleware). diff --git a/src/content/docs/it/5x/guide/using-template-engines.mdx b/src/content/docs/it/5x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..b9ca68f319 --- /dev/null +++ b/src/content/docs/it/5x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Utilizzo di modelli di motori con Express +description: Scopri come integrare e utilizzare modelli di motori come Pug, Manubri ed EJS con Express.js per rendere le pagine HTML dinamiche in modo efficiente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Un motore *modello* ti permette di utilizzare file di template statici nella tua applicazione. Al runtime, il modello del motore sostituisce le variabili +in un modello di file con valori reali, e trasforma il modello in un file HTML inviato al client. +Questo approccio rende più facile progettare una pagina HTML. + +Il [generatore di applicazioni Express](/en/starter/generator) utilizza [Pug](https://pugjs.org/api/getting-started.html) come predefinito, ma supporta anche [Handlebars](https://www.npmjs.com/package/handlebars), e [EJS](https://www.npmjs.com/package/ejs), tra gli altri. + +Per rendere i file dei modelli, imposta le seguenti [proprietà delle impostazioni dell'applicazione](/en/4x/api#app.set), nel file `app.js` predefinito creato dal generatore: + +* `views`, la directory dove si trovano i file del modello. Eg: `app.set('views', './views')`. + Questo valore predefinito è la directory `views` nella directory radice dell'applicazione. +* `view engine`, il modello motore da usare. Ad esempio, per usare il motore modello Pug: `app.set('view engine', 'pug')`. + +Quindi installare il corrispondente pacchetto npm del motore del modello; per esempio per installare Pug: + +```bash +$ npm install pug --save +``` + + +Motori di modelli conformi ad espresso, come Pug esportano una funzione chiamata `__express(filePath, options, callback)`, +che `res.render()` chiama per rendere il codice del modello. + +Alcuni modelli di motori non seguono questa convenzione. La libreria [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +segue questa convenzione mappando tutti i popolari motori di template Node.js, e quindi funziona perfettamente all'interno di Express. + + + +Dopo che il motore di visualizzazione è stato impostato, non è necessario specificare il motore o caricare il modulo del motore modello nella tua app; +Express carica il modulo internamente, per esempio: + +```js +app.set('view engine', 'pug'); +``` + +Quindi, crea un file modello Pug chiamato `index.pug` nella directory `views`, con il seguente contenuto: + +```pug +html + head + title= title + body + h1= message +``` + +Crea un percorso per rendere il file `index.pug`. Se la proprietà `view engine` non è impostata, +è necessario specificare l'estensione del file `view`. Altrimenti, puoi ometterlo. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +Quando effettui una richiesta alla home page, il file `index.pug` verrà renderizzato come HTML. + +La cache del motore di visualizzazione non memorizza in cache il contenuto dell'output del modello, solo il modello sottostante. La vista è ancora ri-renderizzata con ogni richiesta anche quando la cache è accesa. diff --git a/src/content/docs/it/5x/guide/writing-middleware.mdx b/src/content/docs/it/5x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..14157fe349 --- /dev/null +++ b/src/content/docs/it/5x/guide/writing-middleware.mdx @@ -0,0 +1,209 @@ +--- +title: Scrittura middleware per l'utilizzo in applicazioni Express +description: Scopri come scrivere funzioni middleware personalizzate per le applicazioni Express.js, inclusi esempi e migliori pratiche per migliorare la gestione delle richieste e delle risposte. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Le funzioni *Middleware* sono funzioni che hanno accesso al [request object](/en/5x/api#req) (`req`), il [response object](/en/5x/api#res) (`res`), e la funzione `next` nel ciclo request-response dell'applicazione. La funzione `next` è una funzione nel router Express che, quando invocato, esegue il middleware con successo al middleware corrente. + +Le funzioni Middleware possono eseguire le seguenti attività: + +* Esegue qualsiasi codice. +* Effettuare modifiche alla richiesta e agli oggetti di risposta. +* Terminare il ciclo richiesta-risposta. +* Chiama il prossimo middleware nello stack. + +Se la funzione middleware corrente non termina il ciclo richiesta-risposta, deve chiamare `next()` per passare il controllo alla successiva funzione middleware. In caso contrario, la richiesta sarà sospesa. + +La figura seguente mostra gli elementi di una chiamata di una funzione middleware: + +![Elementi di una chiamata di una funzione middleware](/images/express-mw.png) + +A partire da Express 5, le funzioni middleware che restituiscono una Promise chiameranno `next(value)` quando rifiutano o lanciano un errore. `next` verrà chiamato con il valore rifiutato o con l'errore lanciato. + +## Esempio + +Ecco un esempio di una semplice applicazione "Hello World" Express. +Il resto di questo articolo definirà e aggiungerà tre funzioni middleware all'applicazione: +uno chiamato `myLogger` che stampa un semplice messaggio di registro, uno chiamato `requestTime` che +visualizza il timestamp della richiesta HTTP e uno chiamato `validateCookies` che convalida i cookie in entrata. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +### Funzione middleware myLogger + +Ecco un semplice esempio di una funzione middleware chiamata "myLogger". Questa funzione solo stampa +"LOGGED" quando una richiesta all'app passa attraverso di essa. La funzione middleware è assegnata a una variabile +chiamata `myLogger`. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +Notare la chiamata sopra a `next()`. Chiamando questa funzione invoca la prossima funzione middleware nell'app +. La funzione `next()` non è una parte del Node. s o Express API, ma è il terzo argomento +che viene passato alla funzione middleware. La funzione `next()` potrebbe essere chiamata qualsiasi cosa, +ma per convenzione è sempre chiamata "next". Per evitare confusione, utilizzare sempre questa convenzione. + + + +Per caricare la funzione middleware, chiama `app.use()`, specificando la funzione middleware. +Ad esempio, il seguente codice carica la funzione middleware `myLogger` prima del percorso al percorso root (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console. og('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Ciao World!'); +}); + +app.listen(3000); +``` + +Ogni volta che l'app riceve una richiesta, stampa il messaggio "LOGGED" al terminale. + +L'ordine di caricamento del middleware è importante: le funzioni middleware che vengono caricate per primo vengono eseguite per prime. + +Se il file `myLogger` viene caricato dopo il percorso verso il percorso root, la richiesta non lo raggiunge mai e l'applicazione non stampa "LOGGED", perché il gestore del percorso del percorso radice termina il ciclo richiesta-risposta. + +La funzione middleware `myLogger` semplicemente stampa un messaggio, poi passa la richiesta alla funzione middleware successiva nello stack chiamando la funzione `next()`. + +### Richiesta funzione Middleware + +Successivamente, creeremo una funzione middleware chiamata "requestTime" e aggiungeremo una proprietà chiamata `requestTime` +all'oggetto richiesta. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +L'app utilizza ora la funzione middleware `requestTime`. Inoltre, la funzione callback del percorso del percorso del percorso di root utilizza la proprietà che la funzione middleware aggiunge a `req` (il oggetto richiesta). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req. equestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app. et('/', (req, res) => { + let responseText = 'Ciao Mondo!
'; + responseText += `Richiesto a: ${req.requestTime}`; + res. end(responseText); +}); + +app.listen(3000); +``` + +Quando si effettua una richiesta alla root dell'app, l'app ora visualizza il timestamp della richiesta nel browser. + +### Middleware function validateCookies + +Infine, creeremo una funzione middleware che convalida i cookie in arrivo e invia una risposta 400 se i cookie non sono validi. + +Ecco una funzione di esempio che convalida i cookie con un servizio asincronico esterno. + +```js +async function cookieValidator(cookies) { + try { + await externallyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Invalid cookies'); + } +} +``` + +Qui utilizziamo il middleware [`cookie-parser`](/en/resources/middleware/cookie-parser) per analizzare i cookie in arrivo fuori dall'oggetto `req` e passarli alla nostra funzione `cookieValidator`. Il middleware `validateCookies` restituisce una Promessa che al momento del rifiuto attiverà automaticamente il nostro gestore di errori. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('. cookieValidator'); + +const app = express(); + +async function validateCookies(req, res, next) { + await cookieValidator(req. ookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// error handler +app. se((err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Nota come `next()` viene chiamato dopo `await cookieValidator(req.cookies)`. Questo assicura che se +`cookieValidator` si risolve, il prossimo middleware nello stack verrà chiamato. Se passi qualcosa +alla funzione `next()` (tranne la stringa `'route'` o `'router'`), Espresso considera l'attuale richiesta +come un errore e salterà tutte le rimanenti funzioni di routing e middleware +. + + + +Poiché hai accesso all'oggetto richiesta, all'oggetto risposta, alla funzione middleware successiva nello stack, e all'intero Node. s API, le possibilità con funzioni middleware sono infinite. + +Per ulteriori informazioni su middleware Express, consultare: [Using Express middleware](/en/guide/using-middleware). + +## Middleware configurabile + +Se hai bisogno del tuo middleware per essere configurabile, esporta una funzione che accetta un oggetto di opzioni o altri parametri, che, poi, restituisce l'implementazione middleware in base ai parametri di input. + +File: `my-middleware.js` + +```js +modulo. xports = function (options) { + return function (req, res, next) { + // Implementa la funzione middleware basata sulle opzioni object + next(); + }; +}; +``` + +Il middleware può ora essere utilizzato come mostrato di seguito. + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Fare riferimento a [cookie-session](https://github.com/expressjs/cookie-session) e [compression](https://github.com/expressjs/compression) per esempi di middleware configurabile. diff --git a/src/content/docs/it/5x/starter/basic-routing.mdx b/src/content/docs/it/5x/starter/basic-routing.mdx new file mode 100644 index 0000000000..e78f4b9025 --- /dev/null +++ b/src/content/docs/it/5x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Instradamento base +description: Impara i fondamenti del routing nelle applicazioni Express.js, tra cui come definire i percorsi, gestire i metodi HTTP e creare gestori del percorso per il tuo server web. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* si riferisce alla determinazione di come un'applicazione risponde a una richiesta di client a un determinato endpoint, che è un URI (o percorso) e un metodo di richiesta HTTP specifico (GET, POST, e così via). + +Ogni percorso può avere una o più funzioni di gestore, che vengono eseguite quando il percorso è abbinato. + +La definizione del percorso assume la seguente struttura: + +```js +app.METHOD(PATH, HANDLER); +``` + +Dove: + +* `app` è un'istanza di `express`. +* `METHOD` è un [metodo di richiesta HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in minuscolo. +* `PATH` è un percorso sul server. +* `HANDLER` è la funzione eseguita quando il percorso è corrispondente. + + + +Questo tutorial presuppone che venga creata un'istanza di `express` chiamata `app` e che il server sia in esecuzione +. Se non hai familiarità con la creazione di un'app e l'avvio, vedi l'esempio Ciao mondo +. + + + +Gli esempi che seguono illustrano la definizione di itinerari semplici. + +Rispondi con `Ciao Mondo!` nella homepage: + +```js +app.get('/', (req, res) => { + res.send('Hello World!'); +}); +``` + +Rispondi a una richiesta POST sul percorso radice (`/`), la home page dell'applicazione: + +```js +app.post('/', (req, res) => { + res.send('Got a POST request'); +}); +``` + +Rispondi a una richiesta PUT al percorso `/user`: + +```js +app.put('/user', (req, res) => { + res.send('Got a PUT request at /user'); +}); +``` + +Rispondi a una richiesta DELETE al percorso `/user`: + +```js +app.delete('/user', (req, res) => { + res.send('Got a DELETE request at /user'); +}); +``` + +Per maggiori dettagli sul routing, consulta la [guida di routing](/en/guide/routing). diff --git a/src/content/docs/it/5x/starter/examples.mdx b/src/content/docs/it/5x/starter/examples.mdx new file mode 100644 index 0000000000..db38886bfd --- /dev/null +++ b/src/content/docs/it/5x/starter/examples.mdx @@ -0,0 +1,49 @@ +--- +title: Esempi espressi +description: Esplora una raccolta di esempi di applicazioni Express.js che coprono vari casi di utilizzo, integrazioni e configurazioni avanzate per aiutarti a imparare e costruire i tuoi progetti. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Questa pagina contiene un elenco di esempi utilizzando Express. + +* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Autenticazione con login e password +* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - Negoziazione di contenuti HTTP +* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Lavorare con sessioni basate su cookie +* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Lavorare con i cookie +* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Trasferimento dei file al client +* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Lavorare con il template JavaScript incorporato (ejs) +* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Creazione pagine di errore +* [error](https://github.com/expressjs/express/tree/master/examples/error) - Lavorare con middleware errore +* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Gestore semplice della richiesta +* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown come modello motore +* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Lavorare con più router Express +* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - controller in stile MVC +* [online](https://github.com/expressjs/express/tree/master/examples/online) - Monitoraggio delle attività degli utenti online con pacchetti `online` e `redis` +* [params](https://github.com/expressjs/express/tree/master/examples/params) - Lavorare con i parametri del percorso +* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Operazioni HTTP multiple sulla stessa risorsa +* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organizzare i percorsi utilizzando una mappa +* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Lavorare con il middleware del percorso +* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizzare percorsi per ogni risorsa +* [search](https://github.com/expressjs/express/tree/master/examples/search) - Cerca API +* [session](https://github.com/expressjs/express/tree/master/examples/session) - sessioni utente +* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Servire file statici +* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Lavorare con gli host virtuali +* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Visualizzazione dinamica +* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Salvataggio dei dati nell'oggetto richiesta tra le chiamate middleware +* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Servizio API semplice + +## Esempi aggiuntivi + +Questi sono alcuni esempi aggiuntivi con integrazioni più estese. + + + +Queste informazioni si riferiscono a siti, prodotti o moduli di terze parti che non sono mantenuti dal team +Expressjs. L'elenco qui non costituisce un'approvazione o una raccomandazione da parte del team di progetto +Expressjs. + + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app con Express e Next.js utilizzando [Prisma](https://www.npmjs.com/package/prisma) come ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM diff --git a/src/content/docs/it/5x/starter/faq.md b/src/content/docs/it/5x/starter/faq.md new file mode 100644 index 0000000000..6e30b48782 --- /dev/null +++ b/src/content/docs/it/5x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: FAQ +description: Trova le risposte alle domande più frequenti su Express.js, inclusi argomenti sulla struttura delle applicazioni, modelli, autenticazione, modelli motori, gestione degli errori e altro ancora. +--- + +## Come dovrei strutturare la mia applicazione? + +Non esiste una risposta definitiva a questa domanda. La risposta dipende da +sulla scala della tua applicazione e del team che è coinvolto. Per essere il più flessibile possibile +, Express non fa ipotesi in termini di struttura. + +Le rotte e altre logiche specifiche per le applicazioni possono vivere in tutti i file +che desideri, in qualsiasi struttura di directory che preferisci. Visualizza i seguenti esempi di ispirazione +: + +- [Elenco delle rotte](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Mappa del percorso](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Inoltre, ci sono estensioni di terze parti per Express, che semplificano alcuni di questi modelli: + +- [Instradamento delle risorse](https://github.com/expressjs/express-resource) + +## Come definisco i modelli? + +Express non ha alcuna nozione di banca dati. Questo concetto è +lasciato fino a moduli Nodo di terze parti, consentendo di +interfaccia con quasi tutti i database. + +Vedi [LoopBack](http://loopback.io) per un framework basato su Espresso che è centrato sui modelli. + +## Come posso autenticare gli utenti? + +L'autenticazione è un'altra area opinionata in cui Express non si avventura +. È possibile utilizzare qualsiasi schema di autenticazione desiderato. +Per un semplice schema username / password, vedere [questo esempio](https://github.com/expressjs/express/tree/master/examples/auth). + +## Quali modelli di motori supporta Express? + +Express supporta qualsiasi modello di motore conforme alla firma `(percorso, locale, callback)`. +Per normalizzare i modelli di interfacce motore e caching, vedere il progetto +[consolidate.js](https://github.com/visionmedia/consolidate.js) +per il supporto. Motori modello non elencati potrebbero ancora supportare la firma Express. + +Per ulteriori informazioni, vedere [Utilizzo di modelli di motori con Express](/en/guide/using-template-engines). + +## Come posso gestire 404 risposte? + +In Express, 404 risposte non sono il risultato di un errore, quindi +il middleware del gestore dell'errore non le catturerà. Questo comportamento è +perché una risposta 404 indica semplicemente l'assenza di lavoro supplementare da fare; +in altre parole, Express ha eseguito tutte le funzioni e i percorsi del middleware, +e ha trovato che nessuno di loro ha risposto. Tutto quello che devi fare +è aggiungere una funzione middleware nella parte inferiore dello stack (sotto tutte le altre funzioni) +per gestire una risposta 404: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Aggiungi percorsi dinamicamente al runtime su un'istanza di `express.Router()` +in modo che i percorsi non siano sostituiti da una funzione middleware. + +## Come faccio a configurare un gestore di errori? + +Definisci middleware per la gestione degli errori allo stesso modo di altri middleware, +tranne con quattro argomenti invece di tre; specificatamente con la firma `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Per ulteriori informazioni, vedere [Gestione degli errori](/en/guide/error-handling). + +## Come faccio a rendere semplice HTML? + +Non lo fate! Non c'è bisogno di "render" HTML con la funzione `res.render()`. +Se hai un file specifico, usa la funzione `res.sendFile()`. +Se stai servendo molti asset da una directory, usa la funzione middleware `express.static()` +. + +## Quale versione di Node.js richiede Express? + +- [Express 4.x](/en/4x/api) richiede Node.js 0.10 o superiore. +- [Express 5.x](/en/5x/api) richiede Node.js 18 o superiore. diff --git a/src/content/docs/it/5x/starter/generator.mdx b/src/content/docs/it/5x/starter/generator.mdx new file mode 100644 index 0000000000..c7504927ad --- /dev/null +++ b/src/content/docs/it/5x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Generatore di applicazioni espresso +description: Scopri come utilizzare lo strumento del generatore di applicazioni Express per creare rapidamente uno scheletro per le applicazioni Express.js, semplificando la configurazione e la configurazione. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Utilizzare lo strumento generatore di applicazioni, `express-generator`, per creare rapidamente uno scheletro di applicazione. + +È possibile eseguire il generatore di applicazioni con il comando `npx` (disponibile in Node.js 8.2.0). + +```bash +$ npx express-generator +``` + +Per le versioni precedenti di Node, installare il generatore di applicazioni come pacchetto globale npm e quindi lanciarlo: + +```bash +$ npm install -g express-generator +$ express +``` + +Visualizza le opzioni del comando con l'opzione `-h`: + +```bash +$ express -h + + Uso: express [options] [dir] + + Opzioni: + + -h, --help informazioni di utilizzo dell'output + --version output il numero di versione + -e, --ejs aggiungi il supporto del motore ejs + --hbs aggiungi il supporto del motore del manubrio + --pug aggiungi il supporto del motore del pug + -H, --hogan aggiungi hogan. s supporto motore + --no-view genera senza motore di visualizzazione + -v, --view aggiungi vista supporto (ejs hbs hjs jade pug twig vash) (valori predefiniti per jade) + -c, --css aggiungi il foglio di stile supporto (less stylus compass sass) (valori predefiniti per css normali) + --git add . itignore + -f, --force force sulla directory non vuota +``` + +Ad esempio, il seguente crea un'app Express chiamata *myapp*. L'app verrà creata in una cartella chiamata *myapp* nella directory di lavoro corrente e il motore di visualizzazione sarà impostato su Pug: + +```bash +$ express --view=pug myapp + + create : myapp + create : myapp/package.json + create : myapp/app. s + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/route + create : myapp/routes/index. s + create : myapp/routes/users. s + create : myapp/public/stylesheets + create : myapp/public/stylesheets/style. ss + create : myapp/views + create : myapp/views/index. ug + create : myapp/views/layout.pug + create : myapp/views/error. ug + create : myapp/bin + create : myapp/bin/www +``` + +Quindi installare dipendenze: + +```bash +$ cd myapp +$ npm install +``` + +Su MacOS o Linux, esegui l'app con questo comando: + +```bash +$ DEBUG=myapp:* npm start +``` + +Su Windows Command Prompt, utilizzare questo comando: + +```bash +> imposta DEBUG=myapp:* & npm start +``` + +Su Windows PowerShell, utilizzare questo comando: + +```bash +PS> $env:DEBUG='myapp:*'; npm start +``` + +Quindi, caricare `http://localhost:3000/` nel tuo browser per accedere all'app. + +L'app generata ha la seguente struttura di directory: + +```bash +. +├── app.js +├── bin +│ └── www +├── package.json +├── public +│ ├── images +│ ├── javascripts +│ └── stylesheets +│ └── style.css +├── routes +│ ├── index.js +│ └── users.js +└── views + ├── error.pug + ├── index.pug + └── layout.pug + +7 directories, 9 files +``` + + + +La struttura delle app creata dal generatore è solo uno dei tanti modi per strutturare le app Express. +Sentitevi liberi di utilizzare questa struttura o modificarla per soddisfare al meglio le vostre esigenze. + + diff --git a/src/content/docs/it/5x/starter/hello-world.mdx b/src/content/docs/it/5x/starter/hello-world.mdx new file mode 100644 index 0000000000..ebb1cf18e4 --- /dev/null +++ b/src/content/docs/it/5x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Ciao esempio mondiale +description: Inizia con Express.js costruendo una semplice applicazione 'Ciao Mondo', dimostrando la configurazione di base e la creazione di server per i principianti. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Incorporato qui sotto è essenzialmente l'app Express più semplice che puoi creare. Si tratta di un singolo file app +— *non* quello che si otterrebbe se si utilizza il [Express generator](/en/starter/generator), che +crea il ponteggio per un'app completa con numerosi file JavaScript, modelli Jade e sottodirectory +per vari scopi. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res. end('Hello World!'); +}); + +app.listen(port, () => { + console.log(`Example app listening on port ${port}`); +}); +``` + +Questa app avvia un server e ascolta la porta 3000 per le connessioni. L'app risponde con "Ciao Mondo!" per le richieste +all'URL radice (`/`) o *route*. Per ogni altro percorso, risponderà con un **404 non trovato**. + +## Esecuzione Localmente + +Crea prima una directory chiamata `myapp`, cambiala ed esegui `npm init`. Quindi, installa `express` come dipendenza, secondo la [guida all'installazione](/en/starter/installing). + +Nella directory `myapp`, crea un file chiamato `app.js` e copia il codice dall'esempio qui sopra. + + + +The `req` (request) and `res` (response) are the exact same objects that Node provides, so you can +invoke `req.pipe()`, `req.on('data', callback)`, and anything else you would do without Express +involved. + + + +Eseguire l'app con il seguente comando: + +```bash +$ node app.js +``` + +Quindi, caricare `http://localhost:3000/` in un browser per vedere l'output. diff --git a/src/content/docs/it/5x/starter/installing.mdx b/src/content/docs/it/5x/starter/installing.mdx new file mode 100644 index 0000000000..f1438460a6 --- /dev/null +++ b/src/content/docs/it/5x/starter/installing.mdx @@ -0,0 +1,41 @@ +--- +title: Installazione +description: Scopri come installare Express.js nel tuo ambiente Node.js, inclusa la creazione della directory del progetto e la gestione delle dipendenze con npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Prima di iniziare, assicurati di avere [Node.js](https://nodejs.org/) 18 o superiore installato. Quindi, creare una directory per la vostra applicazione e navigare in essa. + +```bash +mkdir myapp +cd myapp +``` + +Usa il comando `npm init` per creare un file `package.json` per la tua applicazione. +Per maggiori informazioni sul funzionamento di `package.json`, vedere [Specifiche della gestione di npm.json](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +Questo comando ti richiede un certo numero di cose, come il nome e la versione della tua applicazione. +Per ora, puoi semplicemente premere RETURN per accettare i valori predefiniti per la maggior parte di essi, con la seguente eccezione: + +``` +punto di ingresso: (index.js) +``` + +Inserisci `app.js`, o qualsiasi cosa desideri che sia il nome del file principale. Se vuoi che sia `index.js`, premi RETURN per accettare il nome del file predefinito suggerito. + +Ora, installa Express nella directory `myapp` e salvalo nella lista delle dipendenze. Per esempio: + +```bash +npm install express +``` + +Per installare Express temporaneamente e non aggiungerlo alla lista delle dipendenze: + +```bash +npm installa express --no-save +``` diff --git a/src/content/docs/it/5x/starter/static-files.mdx b/src/content/docs/it/5x/starter/static-files.mdx new file mode 100644 index 0000000000..89d90034cf --- /dev/null +++ b/src/content/docs/it/5x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Servire file statici in Express +description: Comprendi come servire file statici come immagini, CSS e JavaScript nelle applicazioni Express.js utilizzando il middleware 'static' integrato. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Per servire file statici come immagini, file CSS e file JavaScript, utilizzare la funzione middleware integrata `express.static` in Express. + +La firma della funzione è: + +```js +express.static(root, [options]); +``` + +L'argomento `root` specifica la directory radice da cui servire le risorse statiche. +Per ulteriori informazioni sull'argomento `options`, vedere [express.static](/en/5x/api#express.static). + +Per esempio, utilizzare il seguente codice per servire immagini, file CSS e file JavaScript in una directory chiamata `public`: + +```js +app.use(express.static('public')); +``` + +Ora, puoi caricare i file che sono nella directory `public`: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express cerca i file relativi alla directory statica, quindi il nome della directory statica +non fa parte dell'URL. + + + +Per utilizzare più directory di asset statici, chiama la funzione middleware `express.static`: + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express cerca i file nell'ordine in cui si impostano le directory statiche con la funzione middleware `express.static`. + + + +Per ottenere risultati ottimali, utilizza un proxy +inverso cache per migliorare le prestazioni di +che servono risorse statiche. + + + +Per creare un prefisso di percorso virtuale (dove il percorso non esiste effettivamente nel file system) per i file serviti dal `express. funzione tatic`, [specify a mount path](/en/5x/api#app.use) per la directory statica, come mostrato di seguito: + +```js +app.use('/static', express.static('public')); +``` + +Ora puoi caricare i file che sono nella directory `public` dal prefisso del percorso `/static`. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +Tuttavia, il percorso che fornisci alla funzione `express.static` è relativo alla directory da cui avvii il processo `node`. Se si esegue l'app express da un'altra directory, è più sicuro utilizzare il percorso assoluto della directory che si desidera servire: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public')); +``` + +Per maggiori dettagli sulla funzione `serve-static` e sulle sue opzioni, vedere [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/ja/4x/advanced/developing-template-engines.md b/src/content/docs/ja/4x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..34a00b66da --- /dev/null +++ b/src/content/docs/ja/4x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Express 用テンプレートエンジンの開発 +description: App.engine() を使用して Express.js 用のカスタムテンプレートエンジンを開発する方法と、独自のテンプレートレンダリングロジックの作成と統合の例をご覧ください。 +--- + +`app.engine(ext, callback)`メソッドを使用して、独自のテンプレートエンジンを作成します。 `ext`はファイル拡張子を指し、`callback`はテンプレートエンジン関数です。 は、次の項目をパラメータとして受け付けます。ファイルの場所、options オブジェクト、およびコールバック関数です。 + +以下のコードは、`.ntl`ファイルをレンダリングするための非常に単純なテンプレートエンジンを実装した例です。 + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +アプリは `.ntl` ファイルをレンダリングできるようになります。 `views`ディレクトリに`index.ntl`という名前のファイルを作成します。 + +```pug +#title# +#message# +``` + +次に、アプリに次のルートを作成します。 + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +ホームページへのリクエストを行うと、`index.ntl`はHTMLとしてレンダリングされます。 diff --git a/src/content/docs/ja/4x/guide/behind-proxies.mdx b/src/content/docs/ja/4x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..198dc59044 --- /dev/null +++ b/src/content/docs/ja/4x/guide/behind-proxies.mdx @@ -0,0 +1,101 @@ +--- +title: プロキシの背後にあるエクスプレス +description: クライアントの IP アドレスを処理するトラストプロキシ設定を使用するなど、リバース・プロキシの背後で正しく動作するように Express.js アプリケーションを構成する方法を学びます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +リバースプロキシの背後で Express アプリケーションを実行する場合、Express API の中には予想以外の値が返されるものがあります。 これを調整するために `trust proxy` アプリケーションの設定は、Express API のリバースプロキシによって提供された情報を公開するために使用することができます。 最も一般的な問題は、クライアントのIPアドレスを公開するAPIで、リバースプロキシの内部IPアドレスが表示される可能性があります。 + + + +`trust proxy` の設定では、 +リバースプロキシの正確な設定を理解することが重要です。 この設定はリクエストで提供された値を信頼するためです Express での設定の組み合わせが +リバースプロキシの動作と一致することが重要です。 + + + +`trust proxy`を設定するアプリケーションは、次の表に示されている値のいずれかを設定することができます。 + + + + + + + + + + + + + + + + + + + + + +
値
Boolean +`true` の場合、クライアントの IP アドレスは `X-Forwarded-For` ヘッダーの中の一番左のエントリとして理解されます。 + +`false` の場合、アプリはクライアントに直接向いていると理解され、クライアントの IP アドレスは `req.socket.remoteAddress` に由来します。 これはデフォルトの設定です。 + + +`true` に設定する場合、信頼されている最後のリバースプロキシが以下のすべての HTTP ヘッダを削除/上書きすることが重要です: `X-Forwarded-For` 。 `X-Forwarded-Host` と `X-Forwarded-Proto` があれば、クライアントが何らかの値を提供できるかもしれません。 + +
IPアドレス +リバースプロキシとして信頼する IP アドレス、サブネット、または IP アドレスとサブネットの配列。 次のリストに、事前に設定されたサブネット名が表示されます。 + +* loopback - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniqueloc - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +IPアドレスは以下のいずれかの方法で設定できます。 + +```js +app.set('trust proxy', 'loopback'); // specify a single subnet +app.set('trust proxy', 'loopback, 123.123.123.123'); // specify a subnet and an address +app.set('trust proxy', 'loopback, linklocal, uniquelocal'); // specify multiple subnets as CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // specify multiple subnets as an array +``` + +指定された場合、IPアドレスまたはサブネットはアドレス決定プロセスから除外されます。 アプリケーションサーバーに最も近い信頼できないIPアドレスは、クライアントのIPアドレスとして決定されます。 これは `req.socket.remoteAddress` が信頼されているかどうかをチェックすることで動作します。 その場合、`X-Forwarded-For`内の各アドレスは、最初の信頼されていないアドレスまで右から左にチェックされます。 + +
数字 +Expressアプリケーションから離れたホップの最大数のアドレスを使用してください。 `req.socket.remoteAddress` は最初のホップで、残りは右から左への `X-Forwarded-For` ヘッダで探します。 `0`の値は、最初に信頼されていないアドレスが`req.socket.remoteAddress`であることを意味します。つまり、リバースプロキシは存在しません。 + + +この設定を使用する場合は、複数がないことを確認することが重要です。 Expressアプリケーションへの異なる長さのパスは、クライアントが設定されたホップ数よりも少なくすることができるようになります。 それ以外の場合は、クライアントが何らかの価値を提供することができます。 + +
関数 +カスタムトラスト実装。 + +```js +app.set('trust proxy', (ip) => { + if (ip === '127.0.0.1' || ip === '123.123.123.123') + return true; // trusted IPs + else return false; +}); +``` + +
+ +`trust proxy` を有効にすると、次のような影響を与えます。 + +
    +
  • + [req.hostname](/en/api#req.hostname) の値は、 + `X-Forwarded-Host` ヘッダで設定された値から取得されます。 クライアントやプロキシによって設定できます +
    • +
  • + `X-Forwarded-Proto` はリバースプロキシによって設定することで、アプリが https`か`http\` か無効な名前かをアプリに伝えることができます。 この値は [req.protocol](/en/api#req.protocol) で反映されます。 +
    • +
  • + [req.ip](/en/api#req.ip) と [req.ips](/en/api#req.ips) の値は、 + ソケットアドレスと `X-Forwarded-For` ヘッダーに基づいて入力されます。 最初の信頼されていないアドレスから始めます +
    • +
+ +`trust proxy` は、 [proxy-addr](https://www.npmjs.com/package/proxy-addr) パッケージを使用して実装されています。 詳細については、そのドキュメントを参照してください。 diff --git a/src/content/docs/ja/4x/guide/debugging.mdx b/src/content/docs/ja/4x/guide/debugging.mdx new file mode 100644 index 0000000000..97edc6bd46 --- /dev/null +++ b/src/content/docs/ja/4x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Expressのデバッグ +description: DEBUG環境変数を設定して、Express.jsアプリケーションでデバッグログを有効にして使用する方法を学び、トラブルシューティングを強化します。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express で使用されるすべての内部ログを表示するには、アプリを起動するときに `DEBUG` 環境変数を +`express:*` に設定します。 + +```bash +$ DEBUG=express:* node index.js +``` + +Windows では、対応するコマンドを使用します。 + +```bash +> $env:DEBUG = "express:*"; ノードインデックス.js +``` + +[express generator](/en/starter/generator) で生成されたデフォルトのアプリでこのコマンドを実行すると、以下の出力が出力されます。 + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +アプリへのリクエストが行われると、Express コードで指定されたログが表示されます。 + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index.pug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +ルータの実装からのみログを見るには、`DEBUG`の値を`express:router`に設定します。 同様に、アプリケーションの実装からのログのみを見るには、`DEBUG`の値を`express:application`などに設定します。 + +## `express` で生成されたアプリケーション + +`express`コマンドによって生成されたアプリケーションは、`debug`モジュールを使用し、デバッグ名前空間はアプリケーションの名前をスコープします。 + +例えば、 `$ express sample-app` を使用してアプリを生成した場合、次のコマンドでデバッグ文を有効にできます。 + +```bash +$ DEBUG=sample-app:* node ./bin/www +``` + +カンマ区切りの名前のリストを割り当てることで、複数のデバッグ名前空間を指定できます: + +```bash +$ DEBUG=http,mail,express:* node index.js +``` + +## 高度なオプション + +Node.js を介して実行する場合、デバッグログの動作を変更するいくつかの環境変数を設定できます。 + +| 名前 | 目的 | +| ------------------- | --------------------------- | +| `DEBUG` | 特定のデバッグ名前空間を有効/無効にします。 | +| `DEBUG_COLORS` | デバッグ出力で色を使用するかどうか。 | +| `DEBUG_DEPTH` | 物体検査の深さ。 | +| `DEBUG_FD` | デバッグ出力を書き込むファイル記述子。 | +| `DEBUG_SHOW_HIDDEN` | 検査対象オブジェクトに非表示のプロパティを表示します。 | + + + +The environment variables beginning with `DEBUG_` end up being converted into an Options object +that gets used with `%o`/`%O` formatters. +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) の完全な +リストについては Node.js のドキュメントを参照してください。 + + diff --git a/src/content/docs/ja/4x/guide/error-handling.mdx b/src/content/docs/ja/4x/guide/error-handling.mdx new file mode 100644 index 0000000000..f0a21caaeb --- /dev/null +++ b/src/content/docs/ja/4x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: エラー処理 +description: Express.jsが同期コードと非同期コードのエラーを処理する方法を理解し、アプリケーション用のカスタムエラー処理ミドルウェアを実装する方法を学びます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +_Error Handling_は、 +が同期と非同期の両方で発生するエラーをExpress がキャッチして処理する方法を指します。 Expressにはデフォルトのエラー +ハンドラが付属しているので、始めるために自分で書く必要はありません。 + +## キャッチエラー + +Express がルートハンドラと +ミドルウェアの実行中に発生するすべてのエラーをキャッチすることが重要です。 + +ルートハンドラとミドルウェア +内の同期コードで発生するエラーは追加の作業を必要としません。 同期コードがエラーをスローする場合、Expressは +キャッチして処理します。 例: + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Express はこれを独自にキャッチします。 +}); +``` + +For errors returned from asynchronous functions invoked by route handlers +and middleware, you must pass them to the `next()` function, where Express will +catch and process them. 例: + +```js +app.get('/', (req, res, next) => { + fs.readFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Pass errors to Express. + } else { + res.send(data); + } + }); +}); +``` + +Express 5以降、Promise +を返すルートハンドラとミドルウェアは、エラーの拒否またはスロー時に自動的に`next(value)`を呼び出します。 +例: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = await getUserById(req.params.id); + res.send(user); +}); +``` + +If `getUserById` throws an error or rejects, `next` will be called with either +the thrown error or the rejected value. 拒否された値が指定されていない場合、 `next` +はExpress ルータが提供するデフォルトの Error オブジェクトで呼び出されます。 + +`next()`関数に何かを渡した場合（`'route'`を除く）。 +Expressは現在のリクエストをエラーとみなし、 +残っている非エラー処理ルーティングとミドルウェア関数をスキップします。 + +シーケンス内のコールバックがデータを提供しない場合、エラーのみを提供する場合は、次のように +このコードを簡素化できます: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +In the above example, `next` is provided as the callback for `fs.writeFile`, +which is called with or without errors. エラーがなければ、2番目の +ハンドラが実行されます。そうでなければ、Expressはエラーをキャッチして処理します。 + +route handler または +ミドルウェアによって呼び出された非同期コードで発生するエラーをキャッチし、処理のために Express に渡す必要があります。 例: + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + next(err); + } + }, 100); +}); +``` + +上の例では、 +非同期コードのエラーをキャッチし、Expressに渡すために`try...catch`ブロックを使用しています。 `try...catch` +ブロックが省略された場合、Expressは同期 +ハンドラコードの一部ではないため、エラーをキャッチしません。 + +プロミスを返す関数 +を使うと、`try...catch` のオーバーヘッドを避けることができます。 例: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + .then(() => { + throw new Error('BROKEN'); + }) + .catch(next); // Errors will be passed to Express. +}); +``` + +Since promises automatically catch both synchronous errors and rejected promises, +you can simply provide `next` as the final catch handler and Express will catch errors, +because the catch handler is given the error as the first argument. + +また、非同期コードを些細なものに減らすことで、同期エラー +のキャッチに依存するハンドラのチェーンを使用することもできます。 例: + +```js +app.get('/', [ + function (req, res, next) { + fs.readFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals.data = data; + next(err); + }); + }, + function (req, res) { + res.locals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +上の例では、`readFile` +呼び出しからいくつかの些細な文があります。 `readFile` でエラーが発生した場合、エラーは Express に渡されます。 それ以外の場合は、 +チェーン内の次のハンドラ +で同期エラー処理の世界にすばやく戻ります。 そして、上記の例はデータを処理しようとします。 これが失敗した場合、 +同期エラーハンドラはそれをキャッチします。 `readFile`コールバックの +内でこの処理を行った場合、アプリケーションが終了する可能性があり、Expressエラー +ハンドラは実行されません。 + +どちらの方法を使っても、Expressエラーハンドラを呼び出し、 +アプリケーションを存続させたい場合は Express がエラーを受け取ることを確認する必要があります。 + +## デフォルトのエラーハンドラです + +Expressには、アプリで発生する可能性のあるエラーを処理する内蔵のエラーハンドラが付属しています。 このデフォルトのエラー処理ミドルウェア関数は、ミドルウェア関数スタックの末尾に追加されます。 + +If you pass an error to `next()` and you do not handle it in a custom error +handler, it will be handled by the built-in error handler; the error will be +written to the client with the stack trace. スタックトレースは本番環境に +含まれていません。 + + + +プロダクションモードでアプリを実行するには、環境変数 `NODE_ENV` を `production` に設定します。 + + + +エラーが書き込まれると、次の情報が +応答に追加されます: + +* `res.statusCode` は `err.status` (または `err.statusCode`)から設定されます。 + の場合、この値が4xxまたは5xxの範囲外の場合、500に設定されます。 +* `res.statusMessage` はステータスコードに従って設定されます。 +* 本文は、プロダクション + 環境ではステータスコードメッセージのHTMLになります。そうでなければ、`err.stack`になります。 +* `err.headers` オブジェクトで指定されたヘッダー。 + +If you call `next()` with an error after you have started writing the +response (for example, if you encounter an error while streaming the +response to the client), the Express default error handler closes the +connection and fails the request. + +So when you add a custom error handler, you must delegate to +the default Express error handler, when the headers +have already been sent to the client: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +デフォルトのエラーハンドラは、コード内でエラー +を複数回呼び出して`next()`を呼び出すとトリガされることに注意してください。 カスタムエラー処理ミドルウェアが導入されたとしてもです + +Other error handling middleware can be found at [Express middleware](/en/resources/middleware). + +## エラーハンドラの書き込み + +Define error-handling middleware functions in the same way as other middleware functions, +except error-handling functions have four arguments instead of three: +`(err, req, res, next)`. 例: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +エラー処理ミドルウェアは、他の `app.use()`とルート呼び出しの後に最後に定義します。例: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser.urlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app.use(methodOverride()); +app.use((err, req, res, next) => { + // logic +}); +``` + +ミドルウェア関数内からのレスポンスは、HTMLエラーページ、シンプルなメッセージ、JSON文字列など、あらゆる形式で使用できます。 + +For organizational (and higher-level framework) purposes, you can define +several error-handling middleware functions, much as you would with +regular middleware functions. 例えば、`XHR`とそれ以外のリクエストに対してエラーハンドラ +を定義するには、次のようにします。 + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser.urlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +この例では、一般的な`logErrors`はリクエストと +エラー情報を`stderr`に書き込むことができます。 + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +この例でも、`clientErrorHandler`は以下のように定義されています。この場合、エラーは明示的に次のエラーに渡されます。 + +エラー処理関数で「next」を呼び出さない場合、レスポンスの書き込み(および終了)を行う責任があることに注意してください。 そうでなければ、これらのリクエストは「ハング」し、ガベージコレクションの対象になりません。 + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500).send({ error: 'Something failed!' }); + } else { + next(err); + } +} +``` + +"catch-all" `errorHandler` 関数を以下のように実装します(例えば： + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +複数のコールバック関数を持つルートハンドラがある場合は、`route` パラメータを使用して次のルートハンドラにスキップできます。 例: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user.hasPaid) { + // continue handling this request + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent.find((err, doc) => { + if (err) return next(err); + res.json(doc); + }); + } +); +``` + +この例では、 `getPaidContent` ハンドラはスキップされますが、 `/a_route_background_paywall` の `app` に残っているハンドラは引き続き実行されます。 + + + +`next()`と`next(err)`への呼び出しは、現在のハンドラが完了している状態を示します。 +`next(err)`は、上記のように +に設定されているものを除いて、チェーン内の残りのハンドラをすべてスキップします。 + + diff --git a/src/content/docs/ja/4x/guide/overriding-express-api.md b/src/content/docs/ja/4x/guide/overriding-express-api.md new file mode 100644 index 0000000000..324a52bf6d --- /dev/null +++ b/src/content/docs/ja/4x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Express API のオーバーライド +description: リクエストとレスポンスオブジェクトのメソッドとプロパティをプロトタイプを使用してオーバーライドすることで、Express.js API をカスタマイズして拡張する方法をご覧ください。 +--- + +Express API は、リクエストオブジェクトとレスポンスオブジェクトのさまざまなメソッドとプロパティで構成されています。 これらはプロトタイプによって継承されます。 Express API には 2 つの拡張ポイントがあります。 + +1. `express.request` と `express.response` のグローバルプロトタイプ。 +2. `app.request`と`app.response`でアプリ固有のプロトタイプ。 + +グローバルプロトタイプを変更すると、読み込まれたすべてのExpressアプリが同じプロセスで影響を受けます。 必要に応じて、新しいアプリを作成した後にアプリ固有のプロトタイプを変更するだけで、アプリ固有の変更を行うことができます。 + +## メソッド + +カスタム関数を割り当てることで、既存のメソッドの署名と振る舞いを独自のメソッドで上書きできます。 + +以下は、 [res.sendStatus](/en/4x/api#res.sendStatus) の挙動を上書きした例です。 + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +上記の実装は `res.sendStatus` の元の署名を完全に変更します。 ステータスコード、エンコーディングタイプ、およびメッセージをクライアントに送信できるようになりました。 + +オーバーライドされたメソッドは次のように使用できます。 + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## プロパティー + +Express API のプロパティは以下のいずれかです。 + +1. 割り当てられたプロパティ (例: `req.baseUrl`, `req.originalUrl`) +2. getters (例: `req.secure`, `req.ip`) として定義されています。 + +category 1 のプロパティは、現在のリクエスト-レスポンスサイクルのコンテキストで `request` と `response` オブジェクトに動的に割り当てられます。 彼らの行動はオーバーライドできない + +カテゴリ2のプロパティはExpress API拡張機能APIを使用して上書きすることができます。 + +次のコードは `req.ip` の値をどのように派生するかを書き換えます。 これで、`Client-IP` リクエストヘッダの値を返すだけです。 + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## プロトタイプ + +Express API を提供するためには、Express に渡された request/response オブジェクトを (`app(req) 経由で) 提供します。 res)`は同じプロトタイプチェーンから継承する必要があります。 デフォルトでは、リクエストの `http.IncomingRequest.prototype` と、レスポンスの `http.ServerResponse.prototype` です。 + +必要がない限り、これはアプリケーションレベルでのみ行うことを推奨します。 また、使用されているプロトタイプは、可能な限りデフォルトのプロトタイプに近い機能を備えていることに注意してください。 + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/ja/4x/guide/routing.mdx b/src/content/docs/ja/4x/guide/routing.mdx new file mode 100644 index 0000000000..e851b902c7 --- /dev/null +++ b/src/content/docs/ja/4x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: ルーティング +description: Express.jsアプリケーションでルートを定義して使用する方法を学びます。ルートメソッド、ルートパス、パラメータ、モジュラールーティングにルーターを使用する方法を学びます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* とは、アプリケーションのエンドポイント(URI)がクライアントリクエストに対してどのように応答するかを指します。 +For an introduction to routing, see [Basic routing](/en/starter/basic-routing). + +HTTPメソッドに対応するExpress `app` オブジェクトのメソッドを使用してルーティングを定義します。 +のように、`app。 POST リクエストを処理する GET リクエストと `app.post\` を処理します。 完全なリストについては、 +[app.METHOD](/en/5x/api#app.METHOD) を参照してください。 [app.all()](/en/5x/api#app.all)を使用して、すべてのHTTPメソッドと[app]を処理することもできます。 se()](/en/5x/api#app.use) to +コールバック関数としてミドルウェアを指定する (詳細は [Using middleware](/en/guide/using-middleware) を参照)。 + +これらのルーティングメソッドは、アプリケーションが指定されたルート (エンドポイント) と HTTP メソッドへのリクエストを受け取ったときに呼び出されるコールバック関数 ("handler functions" と呼ばれることもあります) を指定します。 言い換えれば、アプリケーションは指定されたルートとメソッドに一致するリクエストを「リッスン」します。 マッチを検出すると、指定されたコールバック関数を呼び出します。 + +実際、ルーティングメソッドは引数として複数のコールバック関数を持つことができます。 +複数のコールバック関数を使用。 コールバック関数に `next` を引数として渡し、関数の本体内で `next()` を呼び出して、次のコールバックに +を渡すことが重要です。 + +以下のコードは、非常に基本的なルートの例です。 + +```js +const express = require('express'); +const app = express(); + +// respond with "hello world" when a GET request is made to the homepage +app.get('/', (req, res) => { + res.send('hello world'); +}); +``` + +## ルートメソッド + +routeメソッドはHTTPメソッドのいずれかから派生し、`express` クラスのインスタンスに追加されます。 + +以下のコードは、`GET` と `POST` メソッドを定義したルートの例です。 + +```js +// GET method route +app.get('/', (req, res) => { + res.send('GET request to the homepage'); +}); + +// POST method route +app.post('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Expressは、すべてのHTTPリクエストメソッドに対応するメソッドをサポートしています: `get`、`post`など。 +完全なリストについては、 [app.METHOD](/en/5x/api#app.METHOD) を参照してください。 + +特別なルーティングメソッド`app.all()`があり、_all_HTTPリクエストメソッドのパスにミドルウェア関数をロードするために使用されます。 例えば、`GET`を使用しているかどうかに関わらず、ルート`"/secret"へのリクエストに対して以下のハンドラが実行されます。 `POST`、`PUT`、`DELETE\`、または[http module](https://nodejs.org/api/http.html#http_http_methods)でサポートされている他のHTTPリクエストメソッド。 + +```js +app.all('/secret', (req, res, next) => { + console.log('Accessing the secret section ...'); + next(); // pass control to the next handler +}); +``` + +## ルートパス + +ルートパスはリクエストメソッドと組み合わせて、リクエストを作成できるエンドポイントを定義します。 ルートパスは文字列、文字列パターン、または正規表現であることができます。 + + + +In express 5, the characters `?`, `+`, `*`, `[]`, and `()` are handled differently than in version +4, please review the [migration guide](/en/guide/migrating-5#path-syntax) for more information. + + + + + +式4では、`$`のような正規表現は`\`でエスケープする必要があります。 + + + + + +Express は [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) をルート +パスに一致させるために使用します。ルート パスの定義におけるすべての可能性については、path-to-regexp ドキュメントを参照してください。 +[Express Playground Router](https://bjohansebas.github.io/playground-router/)は基本的なExpressルートを +テストするための便利なツールですが、パターンマッチングはサポートされていません。 + + + +クエリ文字列はルートパスの一部ではありません。 + +### 文字列に基づく経路パス + +このルートパスはルートルートのリクエストと一致します。 + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +このルートパスは `/about` へのリクエストと一致します。 + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +このルートパスは `/random.text` へのリクエストと一致します。 + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### 文字列パターンに基づく経路パス + + + +Express 5の文字列パターンは動作しなくなりました。 詳細については、Migration +guideを参照してください。 + + + +このルートパスは `acd` と `abcd` に一致します。 + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +このルートパスは `abcd`、`abbcd`、`abbcd`などにマッチします。 + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +このルートパスは `abcd`、`abxcd`、`abrandoMcd`、`ab123cd`などにマッチします。 + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +このルートパスは `/abe` と `/abcde` に一致します。 + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### 正規表現に基づく経路パス + +このルートパスは "a" と一致します。 + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +このルートは`蝶々`と`トンボ`にマッチしますが、`蝶々`、`トンボフライマン`などにはマッチしません。 + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## ルートパラメータ + +ルートパラメータは、URL 内の位置で指定された値をキャプチャするために使用される名前付きの URL セグメントです。 取得した値は `req.params` オブジェクト内に入力され、パス内でそれぞれのキーとして指定されたrouteパラメータの名前が入力されます。 + +``` +Route path: /users/:userId/books/:bookId +Request URL: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +ルートパラメータを使用してルートを定義するには、以下のようにルートのパスにルートパラメータを指定します。 + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +ルートパラメータの名前は、"単語文字" ([A-Za-z0-9_] )で構成されている必要があります。 + + + +ハイフン(`-`)とドット(`.`)は文字通り解釈されるので、ルートパラメータとともに便利な目的で使うことができます。 + +``` +ルートパス: /flights/:from-:to +Request URL: http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +ルートパス: /platae/:genus.:species +リクエスト URL: http://localhost:3000/platae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +In express 5, Regexp characters are not supported in route paths, for more information please +refer to the [migration guide](/en/guide/migrating-5#path-syntax). + + + +route (ルート)パラメータにマッチする正確な文字列をより詳細に制御するには、括弧(`()`)で正規表現を追加します。 + +``` +ルートパス: /user/:userId(\d+) +リクエスト URL: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +正規表現は通常文字列の一部であるため、 `\` +文字を追加して、`\d+`などのバックスラッシュをエスケープしてください。 + + + + +In Express 4.x, the `*` character in regular expressions is not interpreted in the usual way. 回避策として、`*` の代わりに `{0,}` を使用します。 これはExpress 5で修正される可能性があります。 + + +## Route handlers + +リクエストを処理するために、 [middleware](/en/guide/using-middleware) のように動作する複数のコールバック関数を提供できます。 唯一の例外は、これらのコールバックが `next('route')` を呼び出して、残りのルートコールバックをバイパスすることです。 このメカニズムを使用して、ルート上に事前条件を設定できます。 次に現在のルートを進める理由がなければ次のルートに制御を渡す。 + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params.id === '0') { + return next('route'); + } + res.send(`User ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Special handler for user ID 0'); +}); +``` + +この例では: + +* `GET /user/5` → 最初のルートで処理 → "User 5" を送信 +* `GET /user/0` → 最初のroute ('route')`を呼び出し、次に一致する `/user/:id\` route (ルート) をスキップします。 + +ルートハンドラは、次の例に示すように、関数、関数の配列、または両方の組み合わせの形式で使用できます。 + +単一のコールバック関数はルートを処理できます。 例: + +```js +app.get('/example/a', (req, res) => { + res.send('Hello from A!'); +}); +``` + +複数のコールバック関数がルートを処理できます (`next` オブジェクトを指定してください)。 例: + +```js +app.get( + '/example/b', + (req, res, next) => { + console.log('the response will be sent by the next function ...'); + next(); + }, + (req, res) => { + res.send('Hello from B!'); + } +); +``` + +コールバック関数の配列はルートを処理できます。 例: + +```js +const cb0 = function (req, res, next) { + console.log('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console.log('CB1'); + next(); +}; + +const cb2 = function (req, res) { + res.send('Hello from C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +独立した関数と関数の配列の組み合わせは、ルートを処理することができます。 例: + +```js +const cb0 = function (req, res, next) { + console.log('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console.log('CB1'); + next(); +}; + +app.get( + '/example/d', + [cb0, cb1], + (req, res, next) => { + console.log('the response will be sent by the next function ...'); + next(); + }, + (req, res) => { + res.send('Hello from D!'); + } +); +``` + +## レスポンスメソッド + +次の表のレスポンスオブジェクト (`res`) のメソッドは、クライアントにレスポンスを送信し、リクエスト応答のサイクルを終了することができます。 これらのメソッドのいずれもルートハンドラから呼び出されない場合、クライアントリクエストはハングしたままになります。 + +| 方法 | 説明 | +| --------------------------------------------- | ----------------------------------------- | +| [res.download()](/en/5x/api#res.download) | ダウンロードするファイルを指示します。 | +| [res.end()](/en/5x/api#res.end) | 応答プロセスを終了します。 | +| [res.json()](/en/5x/api#res.json) | JSON 応答を送信します。 | +| [res.jsonp()](/en/5x/api#res.jsonp) | JSONP サポートを使用して JSON 応答を送信します。 | +| [res.redirect()](/en/5x/api#res.redirect) | リダイレクトします。 | +| [res.render()](/en/5x/api#res.render) | ビューテンプレートをレンダリングします。 | +| [res.send()](/en/5x/api#res.send) | さまざまなタイプの応答を送信します。 | +| [res.sendFile()](/en/5x/api#res.sendFile) | ファイルをオクテットストリームとして送信する。 | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | レスポンスステータスコードを設定し、文字列表現をレスポンスボディとして送信します。 | + +## app.route() + +`app.route()` を使用すると、ルートパスに対してチェーン可能なルートハンドラを作成できます。 +パスは単一の場所で指定されているため、モジュラールートを作成することは、冗長性とタイプミスを削減するのに役立ちます。 ルートの詳細については、以下を参照してください: [Router() documentation](/en/5x/api#router)。 + +以下は、`app.route()`を使用して定義されたルートハンドラの例です。 + +```js +app + .route('/book') + .get((req, res) => { + res.send('Get a random book'); + }) + .post((req, res) => { + res.send('Add a book'); + }) + .put((req, res) => { + res.send('Update the book'); + }); +``` + +## express.Router + +`express.Router` クラスを使用して、モジュール化されたマウント可能なルートハンドラを作成します。 `Router`インスタンスは完全なミドルウェアとルーティングシステムです。そのため、しばしば「ミニアプリ」と呼ばれます。 + +次の例では、ルータをモジュールとして作成し、ミドルウェア関数をロードします。 いくつかのルートを定義し、メインアプリのパスにルータモジュールをマウントします。 + +appディレクトリに`birds.js`という名前のルーターファイルを作成します。以下の内容を使用します。 + +```js +const express = require('express'); +const router = express.Router(); + +// middleware that is specific to this router +const timeLog = (req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}; +router.use(timeLog); + +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +次に、アプリにルーターモジュールをロードします。 + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +アプリは `/birds` と `/birds/about` へのリクエストを処理できるようになりました。 同様に、ルート固有の「timeLog」ミドルウェア関数を呼び出します。 + +ただし、親ルート `/birds` にパスパラメータがある場合、サブルートからデフォルトではアクセスできません。 アクセス可能にするには、 `mergeParams` オプションを Router コンストラクタ [reference](/en/5x/api#app.use) に渡す必要があります。 + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/ja/4x/guide/using-middleware.mdx b/src/content/docs/ja/4x/guide/using-middleware.mdx new file mode 100644 index 0000000000..352decfd81 --- /dev/null +++ b/src/content/docs/ja/4x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: ミドルウェアの使用 +description: Express.jsアプリケーションでミドルウェアを使用する方法、アプリケーションレベルおよびルータレベルのミドルウェア、エラー処理、サードパーティミドルウェアの統合などを学びます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express はルーティングおよびミドルウェアの Web フレームワークで、独自の最小限の機能を持っています。Express アプリケーションは、基本的にはミドルウェア関数の一連の呼び出しです。 + +*Middleware* 関数は、[request object](/en/5x/api#req) (`req`) にアクセスできる関数です。 [response object](/en/5x/api#res) (`res`) と、アプリケーションのリクエストレスポンスサイクルの次のミドルウェア関数。 次のミドルウェア関数は通常`next`という名前の変数で表されます。 + +ミドルウェア機能は以下のタスクを実行できます。 + +* 任意のコードを実行します。 +* リクエストとレスポンスオブジェクトに変更を加えます。 +* リクエストレスポンスサイクルを終了します。 +* スタック内の次のミドルウェア関数を呼び出します。 + +現在のミドルウェア関数がリクエスト応答サイクルを終了しない場合は、次のミドルウェア関数に制御を渡すために `next()` を呼び出す必要があります。 そうでなければ、リクエストはハングアップのままになります。 + +Express アプリケーションでは、次のタイプのミドルウェアを使用できます。 + +* [Application-level middleware](#middleware.application) +* [Router-level middleware](#middleware.router) +* [Error-handling middleware](#middleware.error-handling) +* [Built-in middleware](#middleware.built-in) +* [Third-party middleware](#middleware.third-party) + +アプリケーションレベルおよびルーターレベルのミドルウェアは、任意のマウントパスでロードできます。 +また、一連のミドルウェア関数を一緒にロードして、マウントポイントでミドルウェアシステムのサブスタックを作成することもできます。 + +## アプリケーションレベルのミドルウェア + +`app.use()` と `app()` を使用して、アプリケーションレベルのミドルウェアを [app object](/en/5x/api#app) のインスタンスにバインドします。 ETHOD()関数。`METHOD`はミドルウェア関数が小文字で処理するHTTPメソッドです(GET、PUT、POSTなど)。 + +この例では、マウントパスのないミドルウェア関数を示します。 この関数はアプリがリクエストを受け取るたびに実行されます。 + +```js +const express = require('express'); +const app = expresss(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +この例では、`/user/:id` パスにマウントされたミドルウェア関数を示します。 関数は `/user/:id` パス上の任意のタイプの +HTTP リクエストに対して実行されます。 + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +この例ではルートとハンドラ関数(ミドルウェアシステム)を示します。 関数は`/user/:id`パスへのGETリクエストを処理します。 + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +次に、マウントパスを持つ一連のミドルウェア関数をマウントポイントにロードする例を示します。 +これは `/user/:id` パスにHTTPリクエスト情報を出力するミドルウェアのサブスタックを示しています。 + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); +``` + +ルートハンドラを使用すると、パスに複数のルートを定義できます。 下の例では、`/user/:id`パスへのGETリクエストに対する2つのルートを定義しています。 2番目のルートは問題を引き起こすことはありませんが、最初のルートはリクエスト応答サイクルを終了するため、呼び出されることはありません。 + +この例では、`/user/:id`パスへのGETリクエストを処理するミドルウェアサブスタックを示します。 + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req.params.id); + next(); + }, + (req, res, next) => { + res.send('User Info'); + } +); + +// handler for the /user/:id path, which prints the user ID +app.get('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +他のミドルウェア関数をルータのミドルウェアスタックからスキップするには、次のルートに制御を渡すために `next('route')` を呼び出します。 + + + +`next('route')` は、 +`app.METHOD()` または `router.METHOD()` 関数を使用してロードされたミドルウェア関数でのみ動作します。 + + + +この例では、`/user/:id`パスへのGETリクエストを処理するミドルウェアサブスタックを示します。 + +```js +app.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next route + if (req.params.id === '0') next('route'); + // otherwise pass the control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // send a regular response + res.send('regular'); + } +); + +// handler for the /user/:id path, which sends a special response +app.get('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +ミドルウェアは、再利用可能な配列で宣言することもできます。 + +この例では、`/user/:id`パスへのGETリクエストを処理するミドルウェアサブスタックを持つ配列を示しています。 + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req.originalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Request Type:', req.method); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app.get('/user/:id', logStuff, (req, res, next) => { + res.send('User Info'); +}); +``` + +## ルーターレベルのミドルウェア + +ルータレベルのミドルウェアは、`express.Router()`のインスタンスにバインドされている場合を除き、アプリケーションレベルのミドルウェアと同じ方法で動作します。 + +```js +const router = express.Router(); +``` + +`router.use()`と`router.METHOD()`関数を使ってルーターレベルのミドルウェアをロードします。 + +次のコード例は、ルーターレベルのミドルウェアを使用して、アプリケーションレベルのミドルウェアに対して上記のミドルウェアシステムを複製します。 + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// a middleware function with no mount path. This code is executed for every request to the router +router.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); + +// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path +router.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); + +// a middleware sub-stack that handles GET requests to the /user/:id path +router.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next router + if (req.params.id === '0') next('route'); + // otherwise pass control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // render a regular page + res.render('regular'); + } +); + +// handler for the /user/:id path, which renders a special page +router.get('/user/:id', (req, res, next) => { + console.log(req.params.id); + res.render('special'); +}); + +// mount the router on the app +app.use('/', router); +``` + +ルーターのミドルウェア関数の残りをスキップするには、`next('router')` +を呼び出してルーターインスタンスからコントロールを渡します。 + +この例では、`/user/:id`パスへのGETリクエストを処理するミドルウェアサブスタックを示します。 + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// predicate the router with a check and bail out when needed +router.use((req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router.get('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// use the router and 401 anything falling through +app.use('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## エラー処理のミドルウェア + + + +エラー処理ミドルウェアは常に_4つの引数を取ります。 エラー処理ミドルウェア関数として +識別するには、4つの引数を指定する必要があります。 `next` +オブジェクトを使用しなくても、署名を維持するために指定する必要があります。 Otherwise, the `next` object will be +interpreted as regular middleware and will fail to handle errors. + + + +他のミドルウェア関数と同じ方法でエラー処理ミドルウェア関数を定義します 3 つの代わりに 4 つの引数を指定する場合を除き、特に \`(err, req, res, next) というシグネチャを使用します。 + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +エラー処理ミドルウェアの詳細については、[Error handling](/en/guide/error-handling)を参照してください。 + +## 組み込みのミドルウェア + +バージョン 4.x 以降、Express は [Connect](https://github.com/senchalabs/connect) に依存しなくなりました。 The middleware +functions that were previously included with Express are now in separate modules; see [the list of middleware functions](https://github.com/senchalabs/connect#middleware). + +Express には次のミドルウェア関数が組み込まれています。 + +* [express.static](/en/5x/api#express.static) は、HTML ファイル、画像などの静的なアセットを提供します。 +* [express.json](/en/5x/api#express.json) は、JSON ペイロードで受信したリクエストを解析します。 \*\*注意: Express 4.16.0+で利用可能 +* [express.urlencoded](/en/5x/api#express.urlencoded) は、URLエンコードされたペイロードで受信するリクエストを解析します。 \*\*注意: Express 4.16.0+で利用可能 + +## サードパーティのミドルウェア + +サードパーティ製ミドルウェアを使用して、Express アプリに機能を追加します。 + +必要な機能のためにNode.jsモジュールをインストールし、アプリケーション・レベルまたはルータレベルでアプリケーションにロードします。 + +次の例は、cookie-parser関数`cookie-parser`のインストールとロードを示しています。 + +```bash +$ npm install cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// cookie-parsing middleware +app.use(cookieParser()); +``` + +Expressで一般的に使用されるサードパーティミドルウェア関数の部分的なリストについては、[サードパーティミドルウェア](../resources/middleware)を参照してください。 diff --git a/src/content/docs/ja/4x/guide/using-template-engines.mdx b/src/content/docs/ja/4x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..0403b69c27 --- /dev/null +++ b/src/content/docs/ja/4x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Express でテンプレートエンジンを使用する +description: Pug、Handlebars、EJSなどのテンプレートエンジンをExpress.jsで統合して使用し、動的なHTMLページを効率的にレンダリングする方法をご覧ください。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*template engine* を使用すると、アプリケーションで静的なテンプレート ファイルを使用できます。 実行時に、テンプレートエンジンはテンプレートファイルの +変数を実際の値に置き換えます。 をクリックして、テンプレートをクライアントに送信する HTML ファイルに変換します。 +このアプローチにより、HTML ページのデザインが容易になります。 + +The [Express application generator](/en/starter/generator) uses [Pug](https://pugjs.org/api/getting-started.html) as its default, but it also supports [Handlebars](https://www.npmjs.com/package/handlebars), and [EJS](https://www.npmjs.com/package/ejs), among others. + +テンプレートファイルをレンダリングするには、ジェネレータが作成したデフォルトの `app.js` で、次の[アプリケーション設定プロパティ](/en/4x/api#app.set)を設定します。 + +* `views` テンプレートファイルがあるディレクトリ。 例: `app.set('views', './views')` 。 + デフォルトはアプリケーションのルートディレクトリにある `views` ディレクトリです。 +* `viewengine` を使用するテンプレートエンジン。 たとえば、Pugテンプレートエンジンを使用するには、`app.set('view engine', 'pug')`を使います。 + +次に、対応するテンプレートエンジン npm パッケージをインストールします。例えば、Pug をインストールする場合: + +```bash +$ npm install pig --save +``` + + +Pug のような Express 準拠のテンプレートエンジンは、 `__express(filePath, options, callback)` という名前の関数、 `res.render()` がテンプレートコードのレンダリングを呼び出す +をエクスポートします。 + +一部のテンプレートエンジンはこの規約に従っていません。 [@ladjs/integrate](https://www.npmjs.com/package/@ladjs/consolidate) +ライブラリは、一般的な Node.js テンプレートエンジンのすべてをマッピングすることによって、この規則に従っており、したがって、Express 内でシームレスに動作します。 + + + +ビューエンジンが設定された後、アプリケーションにエンジンを指定したりテンプレートエンジンモジュールをロードしたりする必要はありません。 +Express はモジュールを内部的にロードします。例: + +```js +app.set('view engine', 'pug'); +``` + +次に、`views`ディレクトリに`index.pug`という名前のパグテンプレートファイルを作成します。 + +```pug +html + head + title= title + body + h1= message +``` + +`index.pug` ファイルをレンダリングするルートを作成します。 If the `view engine` property is not set, +you must specify the extension of the `view` file. そうでなければ、それを省略することができます。 + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +ホームページへのリクエストを行うと、 `index.pug` ファイルは HTML としてレンダリングされます。 + +ビューエンジンキャッシュはテンプレートの出力の内容をキャッシュせず、元のテンプレート自体のみキャッシュします。 キャッシュがオンの場合でも、ビューはリクエストごとに再レンダリングされます。 diff --git a/src/content/docs/ja/4x/guide/writing-middleware.mdx b/src/content/docs/ja/4x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..f6e9c71200 --- /dev/null +++ b/src/content/docs/ja/4x/guide/writing-middleware.mdx @@ -0,0 +1,239 @@ +--- +title: Express アプリで使用するミドルウェアを書く +description: Express.jsアプリケーション用にカスタムミドルウェア関数を作成する方法を学びます。例や、リクエストとレスポンスの処理を強化するためのベストプラクティスなどです。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Middleware* 関数は、[request object](/en/5x/api#req) (`req`) にアクセスできる関数です。 [response object](/en/5x/api#res) (`res`)とアプリケーションのリクエストレスポンスサイクルの中の `next` 関数。 `next` 関数はExpressルータ内の関数で、呼び出されたときに現在のミドルウェアを継承してミドルウェアを実行します。 + +ミドルウェア機能は以下のタスクを実行できます。 + +* 任意のコードを実行します。 +* リクエストとレスポンスオブジェクトに変更を加えます。 +* リクエストレスポンスサイクルを終了します。 +* スタック内の次のミドルウェアを呼び出します。 + +現在のミドルウェア関数がリクエスト応答サイクルを終了しない場合は、次のミドルウェア関数に制御を渡すために `next()` を呼び出す必要があります。 そうでなければ、リクエストはハングアップのままになります。 + +次の図はミドルウェア関数呼び出しの要素を示しています。 + +
+ + + + + +
+ミドルウェア関数呼び出しの要素 + +
ミドルウェア関数が適用されるHTTPメソッド。
+ +
+ ミドルウェア関数が適用されるパス(ルート)。 +
+ +
+ ミドルウェア関数。 +
+ +
+ 規約ごとに「next」と呼ばれるミドルウェア関数へのコールバック引数。 +
+ +
+ HTTP レスポンス は、 + 規則によって「res」と呼ばれるミドルウェア関数への引数です。 +
+ + +
+
+ +Express 5以降、Promiseを返すミドルウェア関数はエラーの拒否またはスロー時に「next(value)」を呼び出します。 `next`は、拒否された値またはスローされたエラーで呼び出されます。 + +## 例 + +以下は、簡単な「Hello World」エクスプレスアプリケーションの例です。 +The remainder of this article will define and add three middleware functions to the application: +one called `myLogger` that prints a simple log message, one called `requestTime` that +displays the timestamp of the HTTP request, and one called `validateCookies` that validates incoming cookies. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +### ミドルウェア関数 myLogger + +以下は、「myLogger」というミドルウェア関数の簡単な例です。 この関数は、アプリへのリクエストがそれを通過したときに +"LOGGED" を出力します。 ミドルウェア関数は、`myLogger`という名前の +変数に割り当てられます。 + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +上記の `next()` の呼び出しに注目してください。 この関数を呼び出すと、 +アプリケーションで次のミドルウェア関数が呼び出されます。 `next()`関数はノードの一部ではありません。 sまたはExpress APIはミドルウェア関数に渡される3番目の +引数です。 `next()`関数には、 +という名前が付けられますが、慣習的には常に「next」という名前が付けられています。 混乱を避けるため、常にこの規約を使用してください。 + + + +ミドルウェア関数をロードするには、ミドルウェア関数を指定して `app.use()` を呼び出します。 +例えば、次のコードはルートパス(/)の前に`myLogger`ミドルウェア関数をロードします。 + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +アプリがリクエストを受け取るたびに、「LOGGED」というメッセージが端末に出力されます。 + +ミドルウェアのロード順序は重要です。最初にロードされるミドルウェア関数も最初に実行されます。 + +ルートパスの後に`myLogger`がロードされている場合、リクエストは到達せず、アプリは"LOGGED"を出力しません。 なぜなら、ルートパスのルートハンドラは、リクエスト応答サイクルを終了するからです。 + +ミドルウェア関数 `myLogger` は単にメッセージを出力します。 次に、`next()`関数を呼び出すことで、スタック内の次のミドルウェア関数にリクエストを渡します。 + +### ミドルウェア関数requestTime + +次に、"requestTime" というミドルウェア関数を作成し、リクエストオブジェクトに `requestTime` +というプロパティを追加します。 + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +アプリは `requestTime` ミドルウェア関数を使用します。 また、ルートのコールバック関数はミドルウェア関数が`req`（リクエストオブジェクト）に追加するプロパティを使用します。 + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app.get('/', (req, res) => { + let responseText = 'Hello World!
'; + responseText += `Requested at: ${req.requestTime}`; + res.send(responseText); +}); + +app.listen(3000); +``` + +アプリのルートにリクエストを送信すると、アプリはブラウザにリクエストのタイムスタンプを表示するようになりました。 + +### ミドルウェア関数 validateCookies + +最後に、入力されたクッキーを検証するミドルウェア機能を作成し、クッキーが無効な場合に400回のレスポンスを送信します。 + +ここでは、外部非同期サービスで Cookie を検証する機能の例を示します。 + +```js +async function cookieValidator(cookies) { + try { + await externallyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Invalid cookies'); + } +} +``` + +ここでは、[`cookie-parser`](/en/resources/middleware/cookie-parser) ミドルウェアを使用して、`req`オブジェクトから入ってくるCookieを解析し、それを私たちの`cookieValidator`関数に渡します。 `validateCookies`ミドルウェアは、拒否時に自動的にエラーハンドラをトリガーするPromiseを返します。 + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('./cookieValidator'); + +const app = express(); + +async function validateCookies(req, res, next) { + await cookieValidator(req.cookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// error handler +app.use((err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +`await cookieValidator(req.cookies)`の後に`next()`が呼び出されることに注意してください。 これにより、 +`cookieValidator` が解決した場合、スタック内の次のミドルウェアが呼ばれます。 If you pass anything +to the `next()` function (except the string `'route'` or `'router'`), Express regards the current +request as being an error and will skip any remaining non-error handling routing and middleware +functions. + + + +リクエストオブジェクト、レスポンスオブジェクト、スタック内の次のミドルウェア関数、そしてノード全体にアクセスできるためです。 s API、ミドルウェア関数の可能性は無限大です。 + +Express ミドルウェアの詳細については、[Express ミドルウェアを使用する](/en/guide/using-middleware)を参照してください。 + +## 設定可能なミドルウェア + +ミドルウェアの設定が必要な場合は、optionsオブジェクトや他のパラメータを受け付ける関数をエクスポートしてください。 入力パラメータに基づいてミドルウェアの実装を返します。 + +ファイル: `my-middleware.js` + +```js +module.exports = function (options) { + return function (req, res, next) { + // Implement the middleware function based on the options object + next(); + }; +}; +``` + +ミドルウェアを以下のように使用できるようになりました。 + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +構成可能なミドルウェアの例については、 [cookie-session](https://github.com/expressjs/cookie-session) と [compression](https://github.com/expressjs/compression) を参照してください。 diff --git a/src/content/docs/ja/4x/starter/basic-routing.mdx b/src/content/docs/ja/4x/starter/basic-routing.mdx new file mode 100644 index 0000000000..f7e11efeca --- /dev/null +++ b/src/content/docs/ja/4x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: 基本ルーティング +description: Express.jsアプリケーションでルーティングの基礎を学びます。ルートの定義、HTTPメソッドの処理、Webサーバーのルートハンドラの作成などです。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* は、アプリケーションが特定のエンドポイントに対してどのように応答するかを決定することを指します。 これはURI(またはパス)と特定のHTTPリクエストメソッド(GET、POSTなど)です。 + +各ルートは、ルートが一致したときに実行される、1つまたは複数のハンドラ関数を持つことができます。 + +ルート定義は以下の構造をとります: + +```js +app.METHOD(PATH, HANDLER); +``` + +場所: + +* `app` は `express` のインスタンスです。 +* `METHOD` は [HTTP リクエストメソッド](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods) の小文字です。 +* `PATH` はサーバー上のパスです。 +* `HANDLER` はルートが一致したときに実行される関数です。 + + + +このチュートリアルでは、`app` という名前の `express` インスタンスが作成され、サーバーが +動作していることを前提としています。 アプリの作成に慣れていない場合は、Hello world +exampleを参照してください。 + + + +以下の例は、単純なルートの定義を示しています。 + +ホームページの「Hello World!」に返信: + +```js +app.get('/', (req, res) => { + res.send('Hello World!'); +}); +``` + +ルートルート (`/`) の POST リクエストに応答します。アプリケーションのホームページ: + +```js +app.post('/', (req, res) => { + res.send('Got a POST request'); +}); +``` + +`/user`ルートにPUTリクエストに応答します： + +```js +app.put('/user', (req, res) => { + res.send('Got a PUT request at /user'); +}); +``` + +`/user`ルートへのDELETEリクエストに対応: + +```js +app.delete('/user', (req, res) => { + res.send('Got a DELETE request at /user'); +}); +``` + +For more details about routing, see the [routing guide](/en/guide/routing). diff --git a/src/content/docs/ja/4x/starter/examples.mdx b/src/content/docs/ja/4x/starter/examples.mdx new file mode 100644 index 0000000000..ec0da1a1fd --- /dev/null +++ b/src/content/docs/ja/4x/starter/examples.mdx @@ -0,0 +1,45 @@ +--- +title: エクスプレス例 +description: さまざまなユースケース、インテグレーション、高度な構成を網羅した Express.jsアプリケーション例のコレクションをご覧ください。プロジェクトの学習と構築に役立ちます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - ログインとパスワードによる認証 +* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - HTTP コンテンツネゴシエーション +* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - クッキーベースのセッションの操作 +* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - クッキーの操作 +* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - クライアントへのファイルの転送 +* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - 埋め込みJavaScriptテンプレートの操作 (ejs) +* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - エラーページの作成 +* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - エラーミドルウェアの操作 +* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - シンプルなリクエストハンドラ。 +* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown as template engine. +* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - 複数のエクスプレスルーターでの作業 +* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - MVCスタイル コントローラ +* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - オンラインユーザーアクティビティを`オンライン`と`redis`パッケージで追跡 +* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - ルートパラメータの操作 +* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - 同じリソースに対する複数の HTTP 操作 +* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - 地図を使ってルートを整理する +* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - route middleware の操作 +* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - 各リソースごとにルートを整理する +* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Search API +* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - ユーザーセッション +* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - 静的ファイルの提供 +* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - 仮想ホストでの作業 +* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - ビューを動的にレンダリングする +* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - ミドルウェア呼び出し間でリクエストオブジェクトにデータを保存する +* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Simple API service + +## その他の例 + +これらは、より広範な統合を伴ういくつかの追加の例です。 + + + この情報は、 + Expressjsチームがメンテナンスしていないサードパーティのサイト、製品、またはモジュールを指します。 ここでの掲載は、 + Expressjsプロジェクトチームの推奨または推奨を構成するものではありません。 + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - ORMとしてExpressとNext.jsを使用したフルスタックアプリ [Prisma](https://www.npmjs.com/package/prisma) +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - ORMとして [Prisma](https://www.npmjs.com/package/prisma) を使用する Express をTypeScript で REST API diff --git a/src/content/docs/ja/4x/starter/faq.md b/src/content/docs/ja/4x/starter/faq.md new file mode 100644 index 0000000000..89d34a303a --- /dev/null +++ b/src/content/docs/ja/4x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: FAQ +description: Express.jsについてよく寄せられる質問の答えを見つけましょう。その中には、アプリケーション構造、モデル、認証、テンプレートエンジン、エラー処理などのトピックが含まれます。 +--- + +## アプリケーションを構成するにはどうすればいいですか? + +この質問には決定的な答えはありません。 The answer depends +on the scale of your application and the team that is involved. 可能な限り +柔軟性を持たせるために、Expressは構造的な仮定をしません。 + +ルートやその他のアプリケーション固有のロジックは、任意のディレクトリ構造において、 +好きな数のファイルに保存することができます。 View the following +examples for inspiration: + +- [Route listings](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Route map](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +また、Express 用のサードパーティの拡張機能もあり、これらのパターンのいくつかを簡素化します。 + +- [Resourceful routing](https://github.com/expressjs/express-resource) + +## モデルを定義するにはどうすればいいですか? + +Express にはデータベースという概念はありません。 このコンセプトは +サードパーティ製の Node モジュールに残されており、ほぼすべてのデータベースと +インターフェイスを使用できます。 + +モデルを中心とした Express ベースのフレームワークについては [LoopBack](http://loopback.io) を参照してください。 + +## どのようにユーザーを認証できますか? + +Authentication is another opinionated area that Express does not +venture into. 任意の認証スキームを使用できます。 +単純なユーザー名/パスワードスキームについては、[この例](https://github.com/expressjs/express/tree/master/examples/auth)を参照してください。 + +## Expressはどのテンプレートエンジンをサポートしていますか? + +Express は、\`(path, local, callback) 署名に適合するテンプレートエンジンをサポートしています。 +テンプレートエンジンインターフェイスとキャッシュを正規化するには、 +[consolidate.js](https://github.com/visionmedia/consolidate.js) +プロジェクトをサポートしてください。 リストされていないテンプレートエンジンは引き続きExpress 署名をサポートする可能性があります。 + +詳しくは、[Expressでテンプレートエンジンを使用する](/en/guide/using-template-engines)を参照してください。 + +## 404応答はどのように処理すればいいですか? + +Expressでは404応答はエラーの結果ではないため、 +エラーハンドラミドルウェアはそれらを捕捉しません。 This behavior is +because a 404 response simply indicates the absence of additional work to do; +in other words, Express has executed all middleware functions and routes, +and found that none of them responded. All you need to +do is add a middleware function at the very bottom of the stack (below all other functions) +to handle a 404 response: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +`express.Router()` +のインスタンスで実行時にルートを動的に追加することで、ルートはミドルウェア関数に取って代わられません。 + +## エラーハンドラの設定方法は? + +他のミドルウェアと同じ方法でエラー処理ミドルウェア +を定義します。ただし、3つではなく4つの引数を使用します。 具体的にはシグネチャ`(err, req, res, next)`を指定します。 + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +詳細については、[Error handling](/en/guide/error-handling)を参照してください。 + +## プレーンHTMLをレンダリングするにはどうすればいいですか? + +違います！ `res.render()`関数でHTMLを「レンダリング」する必要はありません。 +特定のファイルがある場合は、 `res.sendFile()` 関数を使用します。 +ディレクトリから多くのアセットを提供している場合は、`express.static()` +ミドルウェア関数を使用してください。 + +## Express にはどのバージョンの Node.js が必要ですか? + +- [Express 4.x](/en/4x/api) では、Node.js 0.10 以上が必要です。 +- Express 5.x](/en/5x/api) ではNode.js 18 以上が必要です。 diff --git a/src/content/docs/ja/4x/starter/generator.mdx b/src/content/docs/ja/4x/starter/generator.mdx new file mode 100644 index 0000000000..308ecf85b6 --- /dev/null +++ b/src/content/docs/ja/4x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Express アプリケーションジェネレーター +description: Expressアプリケーションジェネレータツールを使用して、Express.jsアプリケーション用のスケルトンを迅速に作成し、セットアップと構成を合理化する方法を学びます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +アプリケーションジェネレータツール`express-generator`を使用して、アプリケーションスケルトンを素早く作成します。 + +アプリケーションジェネレータは `npx` コマンド (Node.js 8.2.0で利用可能) で実行できます。 + +```bash +$ npx express-generator +``` + +以前のNodeバージョンの場合は、アプリケーションジェネレータをグローバルnpmパッケージとしてインストールしてから起動します。 + +```bash +$ npm install -g express-generator +$ express +``` + +`-h` オプションでコマンドオプションを表示します。 + +```bash +$ express -h + + Usage: express [options] [dir] + + Options: + + -h, --help output usage information + --version output the version number + -e, --ejs add ejs engine support + --hbs add handlebars engine support + --pug add pug engine support + -H, --hogan add hogan.js engine support + --no-view generate without view engine + -v, --view add view support (ejs|hbs|hjs|jade|pug|twig|vash) (defaults to jade) + -c, --css add stylesheet support (less|stylus|compass|sass) (defaults to plain css) + --git add .gitignore + -f, --force force on non-empty directory +``` + +例えば、次のように、*myapp* という名前の Express アプリケーションを作成します。 アプリは現在の作業ディレクトリの *myapp* というフォルダに作成され、ビューエンジンは Pug に設定されます。 + +```bash +$ express --view=pug myapp + + create : myapp + create : myapp/package.json + create : myapp/app.js + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index.js + create : myapp/routes/users.js + create : myapp/public/stylesheets + create : myapp/public/stylesheets/style.css + create : myapp/views + create : myapp/views/index.pug + create : myapp/views/layout.pug + create : myapp/views/error.pug + create : myapp/bin + create : myapp/bin/www +``` + +次に依存関係をインストール: + +```bash +$ cd myapp +$ npm install +``` + +MacOS または Linux では、次のコマンドでアプリを実行します。 + +```bash +$ DEBUG=myapp:* npm start +``` + +Windows コマンドプロンプトでは、次のコマンドを使用します。 + +```bash +> set DEBUG=myapp:* & npm start +``` + +Windows PowerShell では、次のコマンドを使用します。 + +```bash +PS> $env:DEBUG='myapp:*'; npm start +``` + +次に、ブラウザに`http://localhost:3000/`を読み込んでアプリにアクセスします。 + +生成されたアプリには、次のディレクトリ構造があります。 + +```bash +. +├── app.js +├── bin +│ └── www +├── package.json +├── public +│ ├── images +│ ├── javascripts +│ └── stylesheets +│ └── style.css +├── routes +│ ├── index.js +│ └── users.js +└── views + ├── error.pug + ├── index.pug + └── layout.pug + +7 directories, 9 files +``` + + + +ジェネレータによって作成されたアプリ構造は、Express アプリケーションを構成するための多くの方法の1つに過ぎません。 +自由にこの構造を使用するか、あなたのニーズに最適に変更してください。 + + diff --git a/src/content/docs/ja/4x/starter/hello-world.mdx b/src/content/docs/ja/4x/starter/hello-world.mdx new file mode 100644 index 0000000000..edc332e8bc --- /dev/null +++ b/src/content/docs/ja/4x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Hello world example +description: Express.jsを始めるには、シンプルな「Hello World」アプリケーションを構築しましょう。初心者向けの基本的なセットアップとサーバー作成を説明します。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +以下に埋め込まれているのは、基本的に作成できる最も簡単なExpressアプリです。 It is a single file app +— *not* what you'd get if you use the [Express generator](/en/starter/generator), which +creates the scaffolding for a full app with numerous JavaScript files, Jade templates, and +sub-directories for various purposes. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(port, () => { + console.log(`Example app listening on port ${port}`); +}); +``` + +このアプリはサーバーを起動し、接続のためにポート3000をリッスンします。 アプリはルート URL (`/`) または *route* にリクエスト +を返します。 他のすべてのパスについては、**404 Not Found**で応答します。 + +## ローカルで実行中 + +最初に `myapp` という名前のディレクトリを作成し、変更して `npm init` を実行します。 Then, install `express` as a dependency, as per the [installation guide](/en/starter/installing). + +`myapp` ディレクトリで、`app.js`という名前のファイルを作成し、上の例からコードをコピーします。 + + + +The `req` (request) and `res` (response) are the exact same objects that Node provides, so you can +invoke `req.pipe()`, `req.on('data', callback)`, and anything else you would do without Express +involved. + + + +次のコマンドでアプリを実行します。 + +```bash +$ node app.js +``` + +次に、ブラウザーに `http://localhost:3000/` をロードして出力を確認します。 diff --git a/src/content/docs/ja/4x/starter/installing.mdx b/src/content/docs/ja/4x/starter/installing.mdx new file mode 100644 index 0000000000..1be44bf24f --- /dev/null +++ b/src/content/docs/ja/4x/starter/installing.mdx @@ -0,0 +1,50 @@ +--- +title: インストール中 +description: プロジェクトディレクトリの設定やnpmとの依存関係の管理など、Node.js 環境で Express.js をインストールする方法を学びます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +始める前に、 [Node.js](https://nodejs.org/) 0.10 以上がインストールされていることを確認してください。 次に、アプリケーションのディレクトリを作成し、その中に移動します。 + +```bash +mkdir myapp +cd myapp +``` + +`npm init` コマンドを使用して、アプリケーション用の `package.json` ファイルを作成します。 +`package.json` がどのように動作するかについては、[npm の package.json handling](https://docs.npmjs.com/files/package.json) を参照してください。 + +```bash +npm init +``` + +このコマンドを実行すると、アプリケーションの名前やバージョンなど、さまざまなものが表示されます。 +今のところ、RETURNを押すと、ほとんどのデフォルトを受け入れることができます。以下の例外があります。 + +``` +エントリ ポイント: (index.js) +``` + +`app.js`、またはメインファイルの名前を何でも入力します。 `index.js`にしたい場合は、RETURNを押して、推奨されるデフォルトのファイル名を受け入れます。 + +次に、Expressを`myapp`ディレクトリにインストールし、依存関係リストに保存します。 例: + +```bash +npm install Express +``` + +Express を一時的にインストールし、依存関係リストに追加しないでください。 + +```bash +npm install express --no-save +``` + + + +By default with version npm 5.0+, `npm install` adds the module to the `dependencies` list in the +`package.json` file; with earlier versions of npm, you must specify the `--save` option +explicitly. Then, afterwards, running `npm install` in the app directory will automatically +install modules in the dependencies list. + + diff --git a/src/content/docs/ja/4x/starter/static-files.mdx b/src/content/docs/ja/4x/starter/static-files.mdx new file mode 100644 index 0000000000..b72aad560c --- /dev/null +++ b/src/content/docs/ja/4x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Express での静的ファイルの提供 +description: 組み込みの 'static' ミドルウェアを使用して、Express.js アプリケーションで画像、CSS、JavaScript などの静的ファイルを提供する方法を理解します。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +画像、CSSファイル、JavaScriptファイルなどの静的ファイルを提供するには、Express で組み込まれているミドルウェア関数「express.static」を使用します。 + +関数の署名は次のとおりです: + +```js +express.static(root, [options]); +``` + +`root` 引数は、静的アセットを提供するルートディレクトリを指定します。 +引数 `options` の詳細については、 [express.static](/en/5x/api#express.static) を参照してください。 + +例えば、`public`という名前のディレクトリに画像、CSSファイル、JavaScriptファイルを表示するには、次のコードを使用します。 + +```js +app.use(express.static('public')); +``` + +`public` ディレクトリにあるファイルを読み込むことができます。 + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express は静的ディレクトリからの相対的なファイルを検索するので、静的ディレクトリ +の名前は URL の一部ではありません。 + + + +複数の静的アセットディレクトリを使用するには、`express.static` ミドルウェア関数を複数回呼び出します。 + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express は、`express.static` ミドルウェア関数で静的ディレクトリを設定する順序でファイルを検索します。 + + + +For best results, use a reverse +proxy cache to improve performance of +serving static assets. + + + +\`expressで提供されるファイルに対して、仮想パスプレフィックス(ファイルシステム内にパスが実際に存在しない場所)を作成します。 以下に示すように、staticディレクトリの[mount path](/en/5x/api#app.use)を指定します。 + +```js +app.use('/static', express.static('public')); +``` + +`/static` というプレフィックスから、 `public` ディレクトリにあるファイルをロードできます。 + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +しかし、`express.static`関数に与えるパスは、`node`プロセスを起動したディレクトリからの相対パスです。 expressアプリを別のディレクトリから実行する場合、提供したいディレクトリの絶対パスを使用する方が安全です: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public'))); +``` + +`serve-static` 関数とそのオプションの詳細については、 [serve-static](/en/resources/middleware/serve-static) を参照してください。 diff --git a/src/content/docs/ja/5x/advanced/developing-template-engines.md b/src/content/docs/ja/5x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..34a00b66da --- /dev/null +++ b/src/content/docs/ja/5x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Express 用テンプレートエンジンの開発 +description: App.engine() を使用して Express.js 用のカスタムテンプレートエンジンを開発する方法と、独自のテンプレートレンダリングロジックの作成と統合の例をご覧ください。 +--- + +`app.engine(ext, callback)`メソッドを使用して、独自のテンプレートエンジンを作成します。 `ext`はファイル拡張子を指し、`callback`はテンプレートエンジン関数です。 は、次の項目をパラメータとして受け付けます。ファイルの場所、options オブジェクト、およびコールバック関数です。 + +以下のコードは、`.ntl`ファイルをレンダリングするための非常に単純なテンプレートエンジンを実装した例です。 + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +アプリは `.ntl` ファイルをレンダリングできるようになります。 `views`ディレクトリに`index.ntl`という名前のファイルを作成します。 + +```pug +#title# +#message# +``` + +次に、アプリに次のルートを作成します。 + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +ホームページへのリクエストを行うと、`index.ntl`はHTMLとしてレンダリングされます。 diff --git a/src/content/docs/ja/5x/guide/behind-proxies.mdx b/src/content/docs/ja/5x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..198dc59044 --- /dev/null +++ b/src/content/docs/ja/5x/guide/behind-proxies.mdx @@ -0,0 +1,101 @@ +--- +title: プロキシの背後にあるエクスプレス +description: クライアントの IP アドレスを処理するトラストプロキシ設定を使用するなど、リバース・プロキシの背後で正しく動作するように Express.js アプリケーションを構成する方法を学びます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +リバースプロキシの背後で Express アプリケーションを実行する場合、Express API の中には予想以外の値が返されるものがあります。 これを調整するために `trust proxy` アプリケーションの設定は、Express API のリバースプロキシによって提供された情報を公開するために使用することができます。 最も一般的な問題は、クライアントのIPアドレスを公開するAPIで、リバースプロキシの内部IPアドレスが表示される可能性があります。 + + + +`trust proxy` の設定では、 +リバースプロキシの正確な設定を理解することが重要です。 この設定はリクエストで提供された値を信頼するためです Express での設定の組み合わせが +リバースプロキシの動作と一致することが重要です。 + + + +`trust proxy`を設定するアプリケーションは、次の表に示されている値のいずれかを設定することができます。 + + + + + + + + + + + + + + + + + + + + + +
値
Boolean +`true` の場合、クライアントの IP アドレスは `X-Forwarded-For` ヘッダーの中の一番左のエントリとして理解されます。 + +`false` の場合、アプリはクライアントに直接向いていると理解され、クライアントの IP アドレスは `req.socket.remoteAddress` に由来します。 これはデフォルトの設定です。 + + +`true` に設定する場合、信頼されている最後のリバースプロキシが以下のすべての HTTP ヘッダを削除/上書きすることが重要です: `X-Forwarded-For` 。 `X-Forwarded-Host` と `X-Forwarded-Proto` があれば、クライアントが何らかの値を提供できるかもしれません。 + +
IPアドレス +リバースプロキシとして信頼する IP アドレス、サブネット、または IP アドレスとサブネットの配列。 次のリストに、事前に設定されたサブネット名が表示されます。 + +* loopback - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniqueloc - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +IPアドレスは以下のいずれかの方法で設定できます。 + +```js +app.set('trust proxy', 'loopback'); // specify a single subnet +app.set('trust proxy', 'loopback, 123.123.123.123'); // specify a subnet and an address +app.set('trust proxy', 'loopback, linklocal, uniquelocal'); // specify multiple subnets as CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // specify multiple subnets as an array +``` + +指定された場合、IPアドレスまたはサブネットはアドレス決定プロセスから除外されます。 アプリケーションサーバーに最も近い信頼できないIPアドレスは、クライアントのIPアドレスとして決定されます。 これは `req.socket.remoteAddress` が信頼されているかどうかをチェックすることで動作します。 その場合、`X-Forwarded-For`内の各アドレスは、最初の信頼されていないアドレスまで右から左にチェックされます。 + +
数字 +Expressアプリケーションから離れたホップの最大数のアドレスを使用してください。 `req.socket.remoteAddress` は最初のホップで、残りは右から左への `X-Forwarded-For` ヘッダで探します。 `0`の値は、最初に信頼されていないアドレスが`req.socket.remoteAddress`であることを意味します。つまり、リバースプロキシは存在しません。 + + +この設定を使用する場合は、複数がないことを確認することが重要です。 Expressアプリケーションへの異なる長さのパスは、クライアントが設定されたホップ数よりも少なくすることができるようになります。 それ以外の場合は、クライアントが何らかの価値を提供することができます。 + +
関数 +カスタムトラスト実装。 + +```js +app.set('trust proxy', (ip) => { + if (ip === '127.0.0.1' || ip === '123.123.123.123') + return true; // trusted IPs + else return false; +}); +``` + +
+ +`trust proxy` を有効にすると、次のような影響を与えます。 + +
    +
  • + [req.hostname](/en/api#req.hostname) の値は、 + `X-Forwarded-Host` ヘッダで設定された値から取得されます。 クライアントやプロキシによって設定できます +
    • +
  • + `X-Forwarded-Proto` はリバースプロキシによって設定することで、アプリが https`か`http\` か無効な名前かをアプリに伝えることができます。 この値は [req.protocol](/en/api#req.protocol) で反映されます。 +
    • +
  • + [req.ip](/en/api#req.ip) と [req.ips](/en/api#req.ips) の値は、 + ソケットアドレスと `X-Forwarded-For` ヘッダーに基づいて入力されます。 最初の信頼されていないアドレスから始めます +
    • +
+ +`trust proxy` は、 [proxy-addr](https://www.npmjs.com/package/proxy-addr) パッケージを使用して実装されています。 詳細については、そのドキュメントを参照してください。 diff --git a/src/content/docs/ja/5x/guide/debugging.mdx b/src/content/docs/ja/5x/guide/debugging.mdx new file mode 100644 index 0000000000..97edc6bd46 --- /dev/null +++ b/src/content/docs/ja/5x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Expressのデバッグ +description: DEBUG環境変数を設定して、Express.jsアプリケーションでデバッグログを有効にして使用する方法を学び、トラブルシューティングを強化します。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express で使用されるすべての内部ログを表示するには、アプリを起動するときに `DEBUG` 環境変数を +`express:*` に設定します。 + +```bash +$ DEBUG=express:* node index.js +``` + +Windows では、対応するコマンドを使用します。 + +```bash +> $env:DEBUG = "express:*"; ノードインデックス.js +``` + +[express generator](/en/starter/generator) で生成されたデフォルトのアプリでこのコマンドを実行すると、以下の出力が出力されます。 + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +アプリへのリクエストが行われると、Express コードで指定されたログが表示されます。 + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index.pug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +ルータの実装からのみログを見るには、`DEBUG`の値を`express:router`に設定します。 同様に、アプリケーションの実装からのログのみを見るには、`DEBUG`の値を`express:application`などに設定します。 + +## `express` で生成されたアプリケーション + +`express`コマンドによって生成されたアプリケーションは、`debug`モジュールを使用し、デバッグ名前空間はアプリケーションの名前をスコープします。 + +例えば、 `$ express sample-app` を使用してアプリを生成した場合、次のコマンドでデバッグ文を有効にできます。 + +```bash +$ DEBUG=sample-app:* node ./bin/www +``` + +カンマ区切りの名前のリストを割り当てることで、複数のデバッグ名前空間を指定できます: + +```bash +$ DEBUG=http,mail,express:* node index.js +``` + +## 高度なオプション + +Node.js を介して実行する場合、デバッグログの動作を変更するいくつかの環境変数を設定できます。 + +| 名前 | 目的 | +| ------------------- | --------------------------- | +| `DEBUG` | 特定のデバッグ名前空間を有効/無効にします。 | +| `DEBUG_COLORS` | デバッグ出力で色を使用するかどうか。 | +| `DEBUG_DEPTH` | 物体検査の深さ。 | +| `DEBUG_FD` | デバッグ出力を書き込むファイル記述子。 | +| `DEBUG_SHOW_HIDDEN` | 検査対象オブジェクトに非表示のプロパティを表示します。 | + + + +The environment variables beginning with `DEBUG_` end up being converted into an Options object +that gets used with `%o`/`%O` formatters. +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) の完全な +リストについては Node.js のドキュメントを参照してください。 + + diff --git a/src/content/docs/ja/5x/guide/error-handling.mdx b/src/content/docs/ja/5x/guide/error-handling.mdx new file mode 100644 index 0000000000..f0a21caaeb --- /dev/null +++ b/src/content/docs/ja/5x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: エラー処理 +description: Express.jsが同期コードと非同期コードのエラーを処理する方法を理解し、アプリケーション用のカスタムエラー処理ミドルウェアを実装する方法を学びます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +_Error Handling_は、 +が同期と非同期の両方で発生するエラーをExpress がキャッチして処理する方法を指します。 Expressにはデフォルトのエラー +ハンドラが付属しているので、始めるために自分で書く必要はありません。 + +## キャッチエラー + +Express がルートハンドラと +ミドルウェアの実行中に発生するすべてのエラーをキャッチすることが重要です。 + +ルートハンドラとミドルウェア +内の同期コードで発生するエラーは追加の作業を必要としません。 同期コードがエラーをスローする場合、Expressは +キャッチして処理します。 例: + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Express はこれを独自にキャッチします。 +}); +``` + +For errors returned from asynchronous functions invoked by route handlers +and middleware, you must pass them to the `next()` function, where Express will +catch and process them. 例: + +```js +app.get('/', (req, res, next) => { + fs.readFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Pass errors to Express. + } else { + res.send(data); + } + }); +}); +``` + +Express 5以降、Promise +を返すルートハンドラとミドルウェアは、エラーの拒否またはスロー時に自動的に`next(value)`を呼び出します。 +例: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = await getUserById(req.params.id); + res.send(user); +}); +``` + +If `getUserById` throws an error or rejects, `next` will be called with either +the thrown error or the rejected value. 拒否された値が指定されていない場合、 `next` +はExpress ルータが提供するデフォルトの Error オブジェクトで呼び出されます。 + +`next()`関数に何かを渡した場合（`'route'`を除く）。 +Expressは現在のリクエストをエラーとみなし、 +残っている非エラー処理ルーティングとミドルウェア関数をスキップします。 + +シーケンス内のコールバックがデータを提供しない場合、エラーのみを提供する場合は、次のように +このコードを簡素化できます: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +In the above example, `next` is provided as the callback for `fs.writeFile`, +which is called with or without errors. エラーがなければ、2番目の +ハンドラが実行されます。そうでなければ、Expressはエラーをキャッチして処理します。 + +route handler または +ミドルウェアによって呼び出された非同期コードで発生するエラーをキャッチし、処理のために Express に渡す必要があります。 例: + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + next(err); + } + }, 100); +}); +``` + +上の例では、 +非同期コードのエラーをキャッチし、Expressに渡すために`try...catch`ブロックを使用しています。 `try...catch` +ブロックが省略された場合、Expressは同期 +ハンドラコードの一部ではないため、エラーをキャッチしません。 + +プロミスを返す関数 +を使うと、`try...catch` のオーバーヘッドを避けることができます。 例: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + .then(() => { + throw new Error('BROKEN'); + }) + .catch(next); // Errors will be passed to Express. +}); +``` + +Since promises automatically catch both synchronous errors and rejected promises, +you can simply provide `next` as the final catch handler and Express will catch errors, +because the catch handler is given the error as the first argument. + +また、非同期コードを些細なものに減らすことで、同期エラー +のキャッチに依存するハンドラのチェーンを使用することもできます。 例: + +```js +app.get('/', [ + function (req, res, next) { + fs.readFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals.data = data; + next(err); + }); + }, + function (req, res) { + res.locals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +上の例では、`readFile` +呼び出しからいくつかの些細な文があります。 `readFile` でエラーが発生した場合、エラーは Express に渡されます。 それ以外の場合は、 +チェーン内の次のハンドラ +で同期エラー処理の世界にすばやく戻ります。 そして、上記の例はデータを処理しようとします。 これが失敗した場合、 +同期エラーハンドラはそれをキャッチします。 `readFile`コールバックの +内でこの処理を行った場合、アプリケーションが終了する可能性があり、Expressエラー +ハンドラは実行されません。 + +どちらの方法を使っても、Expressエラーハンドラを呼び出し、 +アプリケーションを存続させたい場合は Express がエラーを受け取ることを確認する必要があります。 + +## デフォルトのエラーハンドラです + +Expressには、アプリで発生する可能性のあるエラーを処理する内蔵のエラーハンドラが付属しています。 このデフォルトのエラー処理ミドルウェア関数は、ミドルウェア関数スタックの末尾に追加されます。 + +If you pass an error to `next()` and you do not handle it in a custom error +handler, it will be handled by the built-in error handler; the error will be +written to the client with the stack trace. スタックトレースは本番環境に +含まれていません。 + + + +プロダクションモードでアプリを実行するには、環境変数 `NODE_ENV` を `production` に設定します。 + + + +エラーが書き込まれると、次の情報が +応答に追加されます: + +* `res.statusCode` は `err.status` (または `err.statusCode`)から設定されます。 + の場合、この値が4xxまたは5xxの範囲外の場合、500に設定されます。 +* `res.statusMessage` はステータスコードに従って設定されます。 +* 本文は、プロダクション + 環境ではステータスコードメッセージのHTMLになります。そうでなければ、`err.stack`になります。 +* `err.headers` オブジェクトで指定されたヘッダー。 + +If you call `next()` with an error after you have started writing the +response (for example, if you encounter an error while streaming the +response to the client), the Express default error handler closes the +connection and fails the request. + +So when you add a custom error handler, you must delegate to +the default Express error handler, when the headers +have already been sent to the client: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +デフォルトのエラーハンドラは、コード内でエラー +を複数回呼び出して`next()`を呼び出すとトリガされることに注意してください。 カスタムエラー処理ミドルウェアが導入されたとしてもです + +Other error handling middleware can be found at [Express middleware](/en/resources/middleware). + +## エラーハンドラの書き込み + +Define error-handling middleware functions in the same way as other middleware functions, +except error-handling functions have four arguments instead of three: +`(err, req, res, next)`. 例: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +エラー処理ミドルウェアは、他の `app.use()`とルート呼び出しの後に最後に定義します。例: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser.urlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app.use(methodOverride()); +app.use((err, req, res, next) => { + // logic +}); +``` + +ミドルウェア関数内からのレスポンスは、HTMLエラーページ、シンプルなメッセージ、JSON文字列など、あらゆる形式で使用できます。 + +For organizational (and higher-level framework) purposes, you can define +several error-handling middleware functions, much as you would with +regular middleware functions. 例えば、`XHR`とそれ以外のリクエストに対してエラーハンドラ +を定義するには、次のようにします。 + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser.urlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +この例では、一般的な`logErrors`はリクエストと +エラー情報を`stderr`に書き込むことができます。 + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +この例でも、`clientErrorHandler`は以下のように定義されています。この場合、エラーは明示的に次のエラーに渡されます。 + +エラー処理関数で「next」を呼び出さない場合、レスポンスの書き込み(および終了)を行う責任があることに注意してください。 そうでなければ、これらのリクエストは「ハング」し、ガベージコレクションの対象になりません。 + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500).send({ error: 'Something failed!' }); + } else { + next(err); + } +} +``` + +"catch-all" `errorHandler` 関数を以下のように実装します(例えば： + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +複数のコールバック関数を持つルートハンドラがある場合は、`route` パラメータを使用して次のルートハンドラにスキップできます。 例: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user.hasPaid) { + // continue handling this request + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent.find((err, doc) => { + if (err) return next(err); + res.json(doc); + }); + } +); +``` + +この例では、 `getPaidContent` ハンドラはスキップされますが、 `/a_route_background_paywall` の `app` に残っているハンドラは引き続き実行されます。 + + + +`next()`と`next(err)`への呼び出しは、現在のハンドラが完了している状態を示します。 +`next(err)`は、上記のように +に設定されているものを除いて、チェーン内の残りのハンドラをすべてスキップします。 + + diff --git a/src/content/docs/ja/5x/guide/overriding-express-api.md b/src/content/docs/ja/5x/guide/overriding-express-api.md new file mode 100644 index 0000000000..324a52bf6d --- /dev/null +++ b/src/content/docs/ja/5x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Express API のオーバーライド +description: リクエストとレスポンスオブジェクトのメソッドとプロパティをプロトタイプを使用してオーバーライドすることで、Express.js API をカスタマイズして拡張する方法をご覧ください。 +--- + +Express API は、リクエストオブジェクトとレスポンスオブジェクトのさまざまなメソッドとプロパティで構成されています。 これらはプロトタイプによって継承されます。 Express API には 2 つの拡張ポイントがあります。 + +1. `express.request` と `express.response` のグローバルプロトタイプ。 +2. `app.request`と`app.response`でアプリ固有のプロトタイプ。 + +グローバルプロトタイプを変更すると、読み込まれたすべてのExpressアプリが同じプロセスで影響を受けます。 必要に応じて、新しいアプリを作成した後にアプリ固有のプロトタイプを変更するだけで、アプリ固有の変更を行うことができます。 + +## メソッド + +カスタム関数を割り当てることで、既存のメソッドの署名と振る舞いを独自のメソッドで上書きできます。 + +以下は、 [res.sendStatus](/en/4x/api#res.sendStatus) の挙動を上書きした例です。 + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +上記の実装は `res.sendStatus` の元の署名を完全に変更します。 ステータスコード、エンコーディングタイプ、およびメッセージをクライアントに送信できるようになりました。 + +オーバーライドされたメソッドは次のように使用できます。 + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## プロパティー + +Express API のプロパティは以下のいずれかです。 + +1. 割り当てられたプロパティ (例: `req.baseUrl`, `req.originalUrl`) +2. getters (例: `req.secure`, `req.ip`) として定義されています。 + +category 1 のプロパティは、現在のリクエスト-レスポンスサイクルのコンテキストで `request` と `response` オブジェクトに動的に割り当てられます。 彼らの行動はオーバーライドできない + +カテゴリ2のプロパティはExpress API拡張機能APIを使用して上書きすることができます。 + +次のコードは `req.ip` の値をどのように派生するかを書き換えます。 これで、`Client-IP` リクエストヘッダの値を返すだけです。 + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## プロトタイプ + +Express API を提供するためには、Express に渡された request/response オブジェクトを (`app(req) 経由で) 提供します。 res)`は同じプロトタイプチェーンから継承する必要があります。 デフォルトでは、リクエストの `http.IncomingRequest.prototype` と、レスポンスの `http.ServerResponse.prototype` です。 + +必要がない限り、これはアプリケーションレベルでのみ行うことを推奨します。 また、使用されているプロトタイプは、可能な限りデフォルトのプロトタイプに近い機能を備えていることに注意してください。 + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/ja/5x/guide/routing.mdx b/src/content/docs/ja/5x/guide/routing.mdx new file mode 100644 index 0000000000..e851b902c7 --- /dev/null +++ b/src/content/docs/ja/5x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: ルーティング +description: Express.jsアプリケーションでルートを定義して使用する方法を学びます。ルートメソッド、ルートパス、パラメータ、モジュラールーティングにルーターを使用する方法を学びます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* とは、アプリケーションのエンドポイント(URI)がクライアントリクエストに対してどのように応答するかを指します。 +For an introduction to routing, see [Basic routing](/en/starter/basic-routing). + +HTTPメソッドに対応するExpress `app` オブジェクトのメソッドを使用してルーティングを定義します。 +のように、`app。 POST リクエストを処理する GET リクエストと `app.post\` を処理します。 完全なリストについては、 +[app.METHOD](/en/5x/api#app.METHOD) を参照してください。 [app.all()](/en/5x/api#app.all)を使用して、すべてのHTTPメソッドと[app]を処理することもできます。 se()](/en/5x/api#app.use) to +コールバック関数としてミドルウェアを指定する (詳細は [Using middleware](/en/guide/using-middleware) を参照)。 + +これらのルーティングメソッドは、アプリケーションが指定されたルート (エンドポイント) と HTTP メソッドへのリクエストを受け取ったときに呼び出されるコールバック関数 ("handler functions" と呼ばれることもあります) を指定します。 言い換えれば、アプリケーションは指定されたルートとメソッドに一致するリクエストを「リッスン」します。 マッチを検出すると、指定されたコールバック関数を呼び出します。 + +実際、ルーティングメソッドは引数として複数のコールバック関数を持つことができます。 +複数のコールバック関数を使用。 コールバック関数に `next` を引数として渡し、関数の本体内で `next()` を呼び出して、次のコールバックに +を渡すことが重要です。 + +以下のコードは、非常に基本的なルートの例です。 + +```js +const express = require('express'); +const app = express(); + +// respond with "hello world" when a GET request is made to the homepage +app.get('/', (req, res) => { + res.send('hello world'); +}); +``` + +## ルートメソッド + +routeメソッドはHTTPメソッドのいずれかから派生し、`express` クラスのインスタンスに追加されます。 + +以下のコードは、`GET` と `POST` メソッドを定義したルートの例です。 + +```js +// GET method route +app.get('/', (req, res) => { + res.send('GET request to the homepage'); +}); + +// POST method route +app.post('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Expressは、すべてのHTTPリクエストメソッドに対応するメソッドをサポートしています: `get`、`post`など。 +完全なリストについては、 [app.METHOD](/en/5x/api#app.METHOD) を参照してください。 + +特別なルーティングメソッド`app.all()`があり、_all_HTTPリクエストメソッドのパスにミドルウェア関数をロードするために使用されます。 例えば、`GET`を使用しているかどうかに関わらず、ルート`"/secret"へのリクエストに対して以下のハンドラが実行されます。 `POST`、`PUT`、`DELETE\`、または[http module](https://nodejs.org/api/http.html#http_http_methods)でサポートされている他のHTTPリクエストメソッド。 + +```js +app.all('/secret', (req, res, next) => { + console.log('Accessing the secret section ...'); + next(); // pass control to the next handler +}); +``` + +## ルートパス + +ルートパスはリクエストメソッドと組み合わせて、リクエストを作成できるエンドポイントを定義します。 ルートパスは文字列、文字列パターン、または正規表現であることができます。 + + + +In express 5, the characters `?`, `+`, `*`, `[]`, and `()` are handled differently than in version +4, please review the [migration guide](/en/guide/migrating-5#path-syntax) for more information. + + + + + +式4では、`$`のような正規表現は`\`でエスケープする必要があります。 + + + + + +Express は [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) をルート +パスに一致させるために使用します。ルート パスの定義におけるすべての可能性については、path-to-regexp ドキュメントを参照してください。 +[Express Playground Router](https://bjohansebas.github.io/playground-router/)は基本的なExpressルートを +テストするための便利なツールですが、パターンマッチングはサポートされていません。 + + + +クエリ文字列はルートパスの一部ではありません。 + +### 文字列に基づく経路パス + +このルートパスはルートルートのリクエストと一致します。 + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +このルートパスは `/about` へのリクエストと一致します。 + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +このルートパスは `/random.text` へのリクエストと一致します。 + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### 文字列パターンに基づく経路パス + + + +Express 5の文字列パターンは動作しなくなりました。 詳細については、Migration +guideを参照してください。 + + + +このルートパスは `acd` と `abcd` に一致します。 + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +このルートパスは `abcd`、`abbcd`、`abbcd`などにマッチします。 + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +このルートパスは `abcd`、`abxcd`、`abrandoMcd`、`ab123cd`などにマッチします。 + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +このルートパスは `/abe` と `/abcde` に一致します。 + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### 正規表現に基づく経路パス + +このルートパスは "a" と一致します。 + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +このルートは`蝶々`と`トンボ`にマッチしますが、`蝶々`、`トンボフライマン`などにはマッチしません。 + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## ルートパラメータ + +ルートパラメータは、URL 内の位置で指定された値をキャプチャするために使用される名前付きの URL セグメントです。 取得した値は `req.params` オブジェクト内に入力され、パス内でそれぞれのキーとして指定されたrouteパラメータの名前が入力されます。 + +``` +Route path: /users/:userId/books/:bookId +Request URL: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +ルートパラメータを使用してルートを定義するには、以下のようにルートのパスにルートパラメータを指定します。 + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +ルートパラメータの名前は、"単語文字" ([A-Za-z0-9_] )で構成されている必要があります。 + + + +ハイフン(`-`)とドット(`.`)は文字通り解釈されるので、ルートパラメータとともに便利な目的で使うことができます。 + +``` +ルートパス: /flights/:from-:to +Request URL: http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +ルートパス: /platae/:genus.:species +リクエスト URL: http://localhost:3000/platae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +In express 5, Regexp characters are not supported in route paths, for more information please +refer to the [migration guide](/en/guide/migrating-5#path-syntax). + + + +route (ルート)パラメータにマッチする正確な文字列をより詳細に制御するには、括弧(`()`)で正規表現を追加します。 + +``` +ルートパス: /user/:userId(\d+) +リクエスト URL: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +正規表現は通常文字列の一部であるため、 `\` +文字を追加して、`\d+`などのバックスラッシュをエスケープしてください。 + + + + +In Express 4.x, the `*` character in regular expressions is not interpreted in the usual way. 回避策として、`*` の代わりに `{0,}` を使用します。 これはExpress 5で修正される可能性があります。 + + +## Route handlers + +リクエストを処理するために、 [middleware](/en/guide/using-middleware) のように動作する複数のコールバック関数を提供できます。 唯一の例外は、これらのコールバックが `next('route')` を呼び出して、残りのルートコールバックをバイパスすることです。 このメカニズムを使用して、ルート上に事前条件を設定できます。 次に現在のルートを進める理由がなければ次のルートに制御を渡す。 + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params.id === '0') { + return next('route'); + } + res.send(`User ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Special handler for user ID 0'); +}); +``` + +この例では: + +* `GET /user/5` → 最初のルートで処理 → "User 5" を送信 +* `GET /user/0` → 最初のroute ('route')`を呼び出し、次に一致する `/user/:id\` route (ルート) をスキップします。 + +ルートハンドラは、次の例に示すように、関数、関数の配列、または両方の組み合わせの形式で使用できます。 + +単一のコールバック関数はルートを処理できます。 例: + +```js +app.get('/example/a', (req, res) => { + res.send('Hello from A!'); +}); +``` + +複数のコールバック関数がルートを処理できます (`next` オブジェクトを指定してください)。 例: + +```js +app.get( + '/example/b', + (req, res, next) => { + console.log('the response will be sent by the next function ...'); + next(); + }, + (req, res) => { + res.send('Hello from B!'); + } +); +``` + +コールバック関数の配列はルートを処理できます。 例: + +```js +const cb0 = function (req, res, next) { + console.log('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console.log('CB1'); + next(); +}; + +const cb2 = function (req, res) { + res.send('Hello from C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +独立した関数と関数の配列の組み合わせは、ルートを処理することができます。 例: + +```js +const cb0 = function (req, res, next) { + console.log('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console.log('CB1'); + next(); +}; + +app.get( + '/example/d', + [cb0, cb1], + (req, res, next) => { + console.log('the response will be sent by the next function ...'); + next(); + }, + (req, res) => { + res.send('Hello from D!'); + } +); +``` + +## レスポンスメソッド + +次の表のレスポンスオブジェクト (`res`) のメソッドは、クライアントにレスポンスを送信し、リクエスト応答のサイクルを終了することができます。 これらのメソッドのいずれもルートハンドラから呼び出されない場合、クライアントリクエストはハングしたままになります。 + +| 方法 | 説明 | +| --------------------------------------------- | ----------------------------------------- | +| [res.download()](/en/5x/api#res.download) | ダウンロードするファイルを指示します。 | +| [res.end()](/en/5x/api#res.end) | 応答プロセスを終了します。 | +| [res.json()](/en/5x/api#res.json) | JSON 応答を送信します。 | +| [res.jsonp()](/en/5x/api#res.jsonp) | JSONP サポートを使用して JSON 応答を送信します。 | +| [res.redirect()](/en/5x/api#res.redirect) | リダイレクトします。 | +| [res.render()](/en/5x/api#res.render) | ビューテンプレートをレンダリングします。 | +| [res.send()](/en/5x/api#res.send) | さまざまなタイプの応答を送信します。 | +| [res.sendFile()](/en/5x/api#res.sendFile) | ファイルをオクテットストリームとして送信する。 | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | レスポンスステータスコードを設定し、文字列表現をレスポンスボディとして送信します。 | + +## app.route() + +`app.route()` を使用すると、ルートパスに対してチェーン可能なルートハンドラを作成できます。 +パスは単一の場所で指定されているため、モジュラールートを作成することは、冗長性とタイプミスを削減するのに役立ちます。 ルートの詳細については、以下を参照してください: [Router() documentation](/en/5x/api#router)。 + +以下は、`app.route()`を使用して定義されたルートハンドラの例です。 + +```js +app + .route('/book') + .get((req, res) => { + res.send('Get a random book'); + }) + .post((req, res) => { + res.send('Add a book'); + }) + .put((req, res) => { + res.send('Update the book'); + }); +``` + +## express.Router + +`express.Router` クラスを使用して、モジュール化されたマウント可能なルートハンドラを作成します。 `Router`インスタンスは完全なミドルウェアとルーティングシステムです。そのため、しばしば「ミニアプリ」と呼ばれます。 + +次の例では、ルータをモジュールとして作成し、ミドルウェア関数をロードします。 いくつかのルートを定義し、メインアプリのパスにルータモジュールをマウントします。 + +appディレクトリに`birds.js`という名前のルーターファイルを作成します。以下の内容を使用します。 + +```js +const express = require('express'); +const router = express.Router(); + +// middleware that is specific to this router +const timeLog = (req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}; +router.use(timeLog); + +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +次に、アプリにルーターモジュールをロードします。 + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +アプリは `/birds` と `/birds/about` へのリクエストを処理できるようになりました。 同様に、ルート固有の「timeLog」ミドルウェア関数を呼び出します。 + +ただし、親ルート `/birds` にパスパラメータがある場合、サブルートからデフォルトではアクセスできません。 アクセス可能にするには、 `mergeParams` オプションを Router コンストラクタ [reference](/en/5x/api#app.use) に渡す必要があります。 + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/ja/5x/guide/using-middleware.mdx b/src/content/docs/ja/5x/guide/using-middleware.mdx new file mode 100644 index 0000000000..352decfd81 --- /dev/null +++ b/src/content/docs/ja/5x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: ミドルウェアの使用 +description: Express.jsアプリケーションでミドルウェアを使用する方法、アプリケーションレベルおよびルータレベルのミドルウェア、エラー処理、サードパーティミドルウェアの統合などを学びます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express はルーティングおよびミドルウェアの Web フレームワークで、独自の最小限の機能を持っています。Express アプリケーションは、基本的にはミドルウェア関数の一連の呼び出しです。 + +*Middleware* 関数は、[request object](/en/5x/api#req) (`req`) にアクセスできる関数です。 [response object](/en/5x/api#res) (`res`) と、アプリケーションのリクエストレスポンスサイクルの次のミドルウェア関数。 次のミドルウェア関数は通常`next`という名前の変数で表されます。 + +ミドルウェア機能は以下のタスクを実行できます。 + +* 任意のコードを実行します。 +* リクエストとレスポンスオブジェクトに変更を加えます。 +* リクエストレスポンスサイクルを終了します。 +* スタック内の次のミドルウェア関数を呼び出します。 + +現在のミドルウェア関数がリクエスト応答サイクルを終了しない場合は、次のミドルウェア関数に制御を渡すために `next()` を呼び出す必要があります。 そうでなければ、リクエストはハングアップのままになります。 + +Express アプリケーションでは、次のタイプのミドルウェアを使用できます。 + +* [Application-level middleware](#middleware.application) +* [Router-level middleware](#middleware.router) +* [Error-handling middleware](#middleware.error-handling) +* [Built-in middleware](#middleware.built-in) +* [Third-party middleware](#middleware.third-party) + +アプリケーションレベルおよびルーターレベルのミドルウェアは、任意のマウントパスでロードできます。 +また、一連のミドルウェア関数を一緒にロードして、マウントポイントでミドルウェアシステムのサブスタックを作成することもできます。 + +## アプリケーションレベルのミドルウェア + +`app.use()` と `app()` を使用して、アプリケーションレベルのミドルウェアを [app object](/en/5x/api#app) のインスタンスにバインドします。 ETHOD()関数。`METHOD`はミドルウェア関数が小文字で処理するHTTPメソッドです(GET、PUT、POSTなど)。 + +この例では、マウントパスのないミドルウェア関数を示します。 この関数はアプリがリクエストを受け取るたびに実行されます。 + +```js +const express = require('express'); +const app = expresss(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +この例では、`/user/:id` パスにマウントされたミドルウェア関数を示します。 関数は `/user/:id` パス上の任意のタイプの +HTTP リクエストに対して実行されます。 + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +この例ではルートとハンドラ関数(ミドルウェアシステム)を示します。 関数は`/user/:id`パスへのGETリクエストを処理します。 + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +次に、マウントパスを持つ一連のミドルウェア関数をマウントポイントにロードする例を示します。 +これは `/user/:id` パスにHTTPリクエスト情報を出力するミドルウェアのサブスタックを示しています。 + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); +``` + +ルートハンドラを使用すると、パスに複数のルートを定義できます。 下の例では、`/user/:id`パスへのGETリクエストに対する2つのルートを定義しています。 2番目のルートは問題を引き起こすことはありませんが、最初のルートはリクエスト応答サイクルを終了するため、呼び出されることはありません。 + +この例では、`/user/:id`パスへのGETリクエストを処理するミドルウェアサブスタックを示します。 + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req.params.id); + next(); + }, + (req, res, next) => { + res.send('User Info'); + } +); + +// handler for the /user/:id path, which prints the user ID +app.get('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +他のミドルウェア関数をルータのミドルウェアスタックからスキップするには、次のルートに制御を渡すために `next('route')` を呼び出します。 + + + +`next('route')` は、 +`app.METHOD()` または `router.METHOD()` 関数を使用してロードされたミドルウェア関数でのみ動作します。 + + + +この例では、`/user/:id`パスへのGETリクエストを処理するミドルウェアサブスタックを示します。 + +```js +app.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next route + if (req.params.id === '0') next('route'); + // otherwise pass the control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // send a regular response + res.send('regular'); + } +); + +// handler for the /user/:id path, which sends a special response +app.get('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +ミドルウェアは、再利用可能な配列で宣言することもできます。 + +この例では、`/user/:id`パスへのGETリクエストを処理するミドルウェアサブスタックを持つ配列を示しています。 + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req.originalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Request Type:', req.method); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app.get('/user/:id', logStuff, (req, res, next) => { + res.send('User Info'); +}); +``` + +## ルーターレベルのミドルウェア + +ルータレベルのミドルウェアは、`express.Router()`のインスタンスにバインドされている場合を除き、アプリケーションレベルのミドルウェアと同じ方法で動作します。 + +```js +const router = express.Router(); +``` + +`router.use()`と`router.METHOD()`関数を使ってルーターレベルのミドルウェアをロードします。 + +次のコード例は、ルーターレベルのミドルウェアを使用して、アプリケーションレベルのミドルウェアに対して上記のミドルウェアシステムを複製します。 + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// a middleware function with no mount path. This code is executed for every request to the router +router.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); + +// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path +router.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); + +// a middleware sub-stack that handles GET requests to the /user/:id path +router.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next router + if (req.params.id === '0') next('route'); + // otherwise pass control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // render a regular page + res.render('regular'); + } +); + +// handler for the /user/:id path, which renders a special page +router.get('/user/:id', (req, res, next) => { + console.log(req.params.id); + res.render('special'); +}); + +// mount the router on the app +app.use('/', router); +``` + +ルーターのミドルウェア関数の残りをスキップするには、`next('router')` +を呼び出してルーターインスタンスからコントロールを渡します。 + +この例では、`/user/:id`パスへのGETリクエストを処理するミドルウェアサブスタックを示します。 + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// predicate the router with a check and bail out when needed +router.use((req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router.get('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// use the router and 401 anything falling through +app.use('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## エラー処理のミドルウェア + + + +エラー処理ミドルウェアは常に_4つの引数を取ります。 エラー処理ミドルウェア関数として +識別するには、4つの引数を指定する必要があります。 `next` +オブジェクトを使用しなくても、署名を維持するために指定する必要があります。 Otherwise, the `next` object will be +interpreted as regular middleware and will fail to handle errors. + + + +他のミドルウェア関数と同じ方法でエラー処理ミドルウェア関数を定義します 3 つの代わりに 4 つの引数を指定する場合を除き、特に \`(err, req, res, next) というシグネチャを使用します。 + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +エラー処理ミドルウェアの詳細については、[Error handling](/en/guide/error-handling)を参照してください。 + +## 組み込みのミドルウェア + +バージョン 4.x 以降、Express は [Connect](https://github.com/senchalabs/connect) に依存しなくなりました。 The middleware +functions that were previously included with Express are now in separate modules; see [the list of middleware functions](https://github.com/senchalabs/connect#middleware). + +Express には次のミドルウェア関数が組み込まれています。 + +* [express.static](/en/5x/api#express.static) は、HTML ファイル、画像などの静的なアセットを提供します。 +* [express.json](/en/5x/api#express.json) は、JSON ペイロードで受信したリクエストを解析します。 \*\*注意: Express 4.16.0+で利用可能 +* [express.urlencoded](/en/5x/api#express.urlencoded) は、URLエンコードされたペイロードで受信するリクエストを解析します。 \*\*注意: Express 4.16.0+で利用可能 + +## サードパーティのミドルウェア + +サードパーティ製ミドルウェアを使用して、Express アプリに機能を追加します。 + +必要な機能のためにNode.jsモジュールをインストールし、アプリケーション・レベルまたはルータレベルでアプリケーションにロードします。 + +次の例は、cookie-parser関数`cookie-parser`のインストールとロードを示しています。 + +```bash +$ npm install cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// cookie-parsing middleware +app.use(cookieParser()); +``` + +Expressで一般的に使用されるサードパーティミドルウェア関数の部分的なリストについては、[サードパーティミドルウェア](../resources/middleware)を参照してください。 diff --git a/src/content/docs/ja/5x/guide/using-template-engines.mdx b/src/content/docs/ja/5x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..0403b69c27 --- /dev/null +++ b/src/content/docs/ja/5x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Express でテンプレートエンジンを使用する +description: Pug、Handlebars、EJSなどのテンプレートエンジンをExpress.jsで統合して使用し、動的なHTMLページを効率的にレンダリングする方法をご覧ください。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*template engine* を使用すると、アプリケーションで静的なテンプレート ファイルを使用できます。 実行時に、テンプレートエンジンはテンプレートファイルの +変数を実際の値に置き換えます。 をクリックして、テンプレートをクライアントに送信する HTML ファイルに変換します。 +このアプローチにより、HTML ページのデザインが容易になります。 + +The [Express application generator](/en/starter/generator) uses [Pug](https://pugjs.org/api/getting-started.html) as its default, but it also supports [Handlebars](https://www.npmjs.com/package/handlebars), and [EJS](https://www.npmjs.com/package/ejs), among others. + +テンプレートファイルをレンダリングするには、ジェネレータが作成したデフォルトの `app.js` で、次の[アプリケーション設定プロパティ](/en/4x/api#app.set)を設定します。 + +* `views` テンプレートファイルがあるディレクトリ。 例: `app.set('views', './views')` 。 + デフォルトはアプリケーションのルートディレクトリにある `views` ディレクトリです。 +* `viewengine` を使用するテンプレートエンジン。 たとえば、Pugテンプレートエンジンを使用するには、`app.set('view engine', 'pug')`を使います。 + +次に、対応するテンプレートエンジン npm パッケージをインストールします。例えば、Pug をインストールする場合: + +```bash +$ npm install pig --save +``` + + +Pug のような Express 準拠のテンプレートエンジンは、 `__express(filePath, options, callback)` という名前の関数、 `res.render()` がテンプレートコードのレンダリングを呼び出す +をエクスポートします。 + +一部のテンプレートエンジンはこの規約に従っていません。 [@ladjs/integrate](https://www.npmjs.com/package/@ladjs/consolidate) +ライブラリは、一般的な Node.js テンプレートエンジンのすべてをマッピングすることによって、この規則に従っており、したがって、Express 内でシームレスに動作します。 + + + +ビューエンジンが設定された後、アプリケーションにエンジンを指定したりテンプレートエンジンモジュールをロードしたりする必要はありません。 +Express はモジュールを内部的にロードします。例: + +```js +app.set('view engine', 'pug'); +``` + +次に、`views`ディレクトリに`index.pug`という名前のパグテンプレートファイルを作成します。 + +```pug +html + head + title= title + body + h1= message +``` + +`index.pug` ファイルをレンダリングするルートを作成します。 If the `view engine` property is not set, +you must specify the extension of the `view` file. そうでなければ、それを省略することができます。 + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +ホームページへのリクエストを行うと、 `index.pug` ファイルは HTML としてレンダリングされます。 + +ビューエンジンキャッシュはテンプレートの出力の内容をキャッシュせず、元のテンプレート自体のみキャッシュします。 キャッシュがオンの場合でも、ビューはリクエストごとに再レンダリングされます。 diff --git a/src/content/docs/ja/5x/guide/writing-middleware.mdx b/src/content/docs/ja/5x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..87747e65b1 --- /dev/null +++ b/src/content/docs/ja/5x/guide/writing-middleware.mdx @@ -0,0 +1,209 @@ +--- +title: Express アプリで使用するミドルウェアを書く +description: Express.jsアプリケーション用にカスタムミドルウェア関数を作成する方法を学びます。例や、リクエストとレスポンスの処理を強化するためのベストプラクティスなどです。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Middleware* 関数は、[request object](/en/5x/api#req) (`req`) にアクセスできる関数です。 [response object](/en/5x/api#res) (`res`)とアプリケーションのリクエストレスポンスサイクルの中の `next` 関数。 `next` 関数はExpressルータ内の関数で、呼び出されたときに現在のミドルウェアを継承してミドルウェアを実行します。 + +ミドルウェア機能は以下のタスクを実行できます。 + +* 任意のコードを実行します。 +* リクエストとレスポンスオブジェクトに変更を加えます。 +* リクエストレスポンスサイクルを終了します。 +* スタック内の次のミドルウェアを呼び出します。 + +現在のミドルウェア関数がリクエスト応答サイクルを終了しない場合は、次のミドルウェア関数に制御を渡すために `next()` を呼び出す必要があります。 そうでなければ、リクエストはハングアップのままになります。 + +次の図はミドルウェア関数呼び出しの要素を示しています。 + +![Elements of a middleware function call](/images/express-mw.png) + +Express 5以降、Promiseを返すミドルウェア関数はエラーの拒否またはスロー時に「next(value)」を呼び出します。 `next`は、拒否された値またはスローされたエラーで呼び出されます。 + +## 例 + +以下は、簡単な「Hello World」エクスプレスアプリケーションの例です。 +The remainder of this article will define and add three middleware functions to the application: +one called `myLogger` that prints a simple log message, one called `requestTime` that +displays the timestamp of the HTTP request, and one called `validateCookies` that validates incoming cookies. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +### ミドルウェア関数 myLogger + +以下は、「myLogger」というミドルウェア関数の簡単な例です。 この関数は、アプリへのリクエストがそれを通過したときに +"LOGGED" を出力します。 ミドルウェア関数は、`myLogger`という名前の +変数に割り当てられます。 + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +上記の `next()` の呼び出しに注目してください。 この関数を呼び出すと、 +アプリケーションで次のミドルウェア関数が呼び出されます。 `next()`関数はノードの一部ではありません。 sまたはExpress APIはミドルウェア関数に渡される3番目の +引数です。 `next()`関数には、 +という名前が付けられますが、慣習的には常に「next」という名前が付けられています。 混乱を避けるため、常にこの規約を使用してください。 + + + +ミドルウェア関数をロードするには、ミドルウェア関数を指定して `app.use()` を呼び出します。 +例えば、次のコードはルートパス(/)の前に`myLogger`ミドルウェア関数をロードします。 + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +アプリがリクエストを受け取るたびに、「LOGGED」というメッセージが端末に出力されます。 + +ミドルウェアのロード順序は重要です。最初にロードされるミドルウェア関数も最初に実行されます。 + +ルートパスの後に`myLogger`がロードされている場合、リクエストは到達せず、アプリは"LOGGED"を出力しません。 なぜなら、ルートパスのルートハンドラは、リクエスト応答サイクルを終了するからです。 + +ミドルウェア関数 `myLogger` は単にメッセージを出力します。 次に、`next()`関数を呼び出すことで、スタック内の次のミドルウェア関数にリクエストを渡します。 + +### ミドルウェア関数requestTime + +次に、"requestTime" というミドルウェア関数を作成し、リクエストオブジェクトに `requestTime` +というプロパティを追加します。 + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +アプリは `requestTime` ミドルウェア関数を使用します。 また、ルートのコールバック関数はミドルウェア関数が`req`（リクエストオブジェクト）に追加するプロパティを使用します。 + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app.get('/', (req, res) => { + let responseText = 'Hello World!
'; + responseText += `Requested at: ${req.requestTime}`; + res.send(responseText); +}); + +app.listen(3000); +``` + +アプリのルートにリクエストを送信すると、アプリはブラウザにリクエストのタイムスタンプを表示するようになりました。 + +### ミドルウェア関数 validateCookies + +最後に、入力されたクッキーを検証するミドルウェア機能を作成し、クッキーが無効な場合に400回のレスポンスを送信します。 + +ここでは、外部非同期サービスで Cookie を検証する機能の例を示します。 + +```js +async function cookieValidator(cookies) { + try { + await externallyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Invalid cookies'); + } +} +``` + +ここでは、[`cookie-parser`](/en/resources/middleware/cookie-parser) ミドルウェアを使用して、`req`オブジェクトから入ってくるCookieを解析し、それを私たちの`cookieValidator`関数に渡します。 `validateCookies`ミドルウェアは、拒否時に自動的にエラーハンドラをトリガーするPromiseを返します。 + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('./cookieValidator'); + +const app = express(); + +async function validateCookies(req, res, next) { + await cookieValidator(req.cookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// error handler +app.use((err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +`await cookieValidator(req.cookies)`の後に`next()`が呼び出されることに注意してください。 これにより、 +`cookieValidator` が解決した場合、スタック内の次のミドルウェアが呼ばれます。 If you pass anything +to the `next()` function (except the string `'route'` or `'router'`), Express regards the current +request as being an error and will skip any remaining non-error handling routing and middleware +functions. + + + +リクエストオブジェクト、レスポンスオブジェクト、スタック内の次のミドルウェア関数、そしてノード全体にアクセスできるためです。 s API、ミドルウェア関数の可能性は無限大です。 + +Express ミドルウェアの詳細については、[Express ミドルウェアを使用する](/en/guide/using-middleware)を参照してください。 + +## 設定可能なミドルウェア + +ミドルウェアの設定が必要な場合は、optionsオブジェクトや他のパラメータを受け付ける関数をエクスポートしてください。 入力パラメータに基づいてミドルウェアの実装を返します。 + +ファイル: `my-middleware.js` + +```js +module.exports = function (options) { + return function (req, res, next) { + // Implement the middleware function based on the options object + next(); + }; +}; +``` + +ミドルウェアを以下のように使用できるようになりました。 + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +構成可能なミドルウェアの例については、 [cookie-session](https://github.com/expressjs/cookie-session) と [compression](https://github.com/expressjs/compression) を参照してください。 diff --git a/src/content/docs/ja/5x/starter/basic-routing.mdx b/src/content/docs/ja/5x/starter/basic-routing.mdx new file mode 100644 index 0000000000..f7e11efeca --- /dev/null +++ b/src/content/docs/ja/5x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: 基本ルーティング +description: Express.jsアプリケーションでルーティングの基礎を学びます。ルートの定義、HTTPメソッドの処理、Webサーバーのルートハンドラの作成などです。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* は、アプリケーションが特定のエンドポイントに対してどのように応答するかを決定することを指します。 これはURI(またはパス)と特定のHTTPリクエストメソッド(GET、POSTなど)です。 + +各ルートは、ルートが一致したときに実行される、1つまたは複数のハンドラ関数を持つことができます。 + +ルート定義は以下の構造をとります: + +```js +app.METHOD(PATH, HANDLER); +``` + +場所: + +* `app` は `express` のインスタンスです。 +* `METHOD` は [HTTP リクエストメソッド](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods) の小文字です。 +* `PATH` はサーバー上のパスです。 +* `HANDLER` はルートが一致したときに実行される関数です。 + + + +このチュートリアルでは、`app` という名前の `express` インスタンスが作成され、サーバーが +動作していることを前提としています。 アプリの作成に慣れていない場合は、Hello world +exampleを参照してください。 + + + +以下の例は、単純なルートの定義を示しています。 + +ホームページの「Hello World!」に返信: + +```js +app.get('/', (req, res) => { + res.send('Hello World!'); +}); +``` + +ルートルート (`/`) の POST リクエストに応答します。アプリケーションのホームページ: + +```js +app.post('/', (req, res) => { + res.send('Got a POST request'); +}); +``` + +`/user`ルートにPUTリクエストに応答します： + +```js +app.put('/user', (req, res) => { + res.send('Got a PUT request at /user'); +}); +``` + +`/user`ルートへのDELETEリクエストに対応: + +```js +app.delete('/user', (req, res) => { + res.send('Got a DELETE request at /user'); +}); +``` + +For more details about routing, see the [routing guide](/en/guide/routing). diff --git a/src/content/docs/ja/5x/starter/examples.mdx b/src/content/docs/ja/5x/starter/examples.mdx new file mode 100644 index 0000000000..c85510841e --- /dev/null +++ b/src/content/docs/ja/5x/starter/examples.mdx @@ -0,0 +1,49 @@ +--- +title: エクスプレス例 +description: さまざまなユースケース、インテグレーション、高度な構成を網羅した Express.jsアプリケーション例のコレクションをご覧ください。プロジェクトの学習と構築に役立ちます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +このページには、Express を使用した例のリストがあります。 + +* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - ログインとパスワードによる認証 +* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - HTTP コンテンツネゴシエーション +* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - クッキーベースのセッションの操作 +* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - クッキーの操作 +* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - クライアントへのファイルの転送 +* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - 埋め込みJavaScriptテンプレートの操作 (ejs) +* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - エラーページの作成 +* [error](https://github.com/expressjs/express/tree/master/examples/error) - エラーミドルウェアの操作 +* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - シンプルなリクエストハンドラ。 +* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown as template engine. +* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - 複数のエクスプレスルーターでの作業 +* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - MVCスタイル コントローラ +* [online](https://github.com/expressjs/express/tree/master/examples/online) - オンラインユーザーアクティビティを`オンライン`と`redis`パッケージで追跡 +* [params](https://github.com/expressjs/express/tree/master/examples/params) - ルートパラメータの操作 +* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - 同じリソースに対する複数の HTTP 操作 +* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - 地図を使ってルートを整理する +* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - route middleware の操作 +* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - 各リソースごとにルートを整理する +* [search](https://github.com/expressjs/express/tree/master/examples/search) - Search API +* [session](https://github.com/expressjs/express/tree/master/examples/session) - ユーザーセッション +* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - 静的ファイルの提供 +* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - 仮想ホストでの作業 +* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - ビューを動的にレンダリングする +* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - ミドルウェア呼び出し間でリクエストオブジェクトにデータを保存する +* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Simple API service + +## その他の例 + +これらは、より広範な統合を伴ういくつかの追加の例です。 + + + +この情報は、 +Expressjsチームがメンテナンスしていないサードパーティのサイト、製品、またはモジュールを指します。 ここでの掲載は、 +Expressjsプロジェクトチームの推奨または推奨を構成するものではありません。 + + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - ORMとしてExpressとNext.jsを使用したフルスタックアプリ [Prisma](https://www.npmjs.com/package/prisma) +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - ORMとして [Prisma](https://www.npmjs.com/package/prisma) を使用する Express をTypeScript で REST API diff --git a/src/content/docs/ja/5x/starter/faq.md b/src/content/docs/ja/5x/starter/faq.md new file mode 100644 index 0000000000..89d34a303a --- /dev/null +++ b/src/content/docs/ja/5x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: FAQ +description: Express.jsについてよく寄せられる質問の答えを見つけましょう。その中には、アプリケーション構造、モデル、認証、テンプレートエンジン、エラー処理などのトピックが含まれます。 +--- + +## アプリケーションを構成するにはどうすればいいですか? + +この質問には決定的な答えはありません。 The answer depends +on the scale of your application and the team that is involved. 可能な限り +柔軟性を持たせるために、Expressは構造的な仮定をしません。 + +ルートやその他のアプリケーション固有のロジックは、任意のディレクトリ構造において、 +好きな数のファイルに保存することができます。 View the following +examples for inspiration: + +- [Route listings](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Route map](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +また、Express 用のサードパーティの拡張機能もあり、これらのパターンのいくつかを簡素化します。 + +- [Resourceful routing](https://github.com/expressjs/express-resource) + +## モデルを定義するにはどうすればいいですか? + +Express にはデータベースという概念はありません。 このコンセプトは +サードパーティ製の Node モジュールに残されており、ほぼすべてのデータベースと +インターフェイスを使用できます。 + +モデルを中心とした Express ベースのフレームワークについては [LoopBack](http://loopback.io) を参照してください。 + +## どのようにユーザーを認証できますか? + +Authentication is another opinionated area that Express does not +venture into. 任意の認証スキームを使用できます。 +単純なユーザー名/パスワードスキームについては、[この例](https://github.com/expressjs/express/tree/master/examples/auth)を参照してください。 + +## Expressはどのテンプレートエンジンをサポートしていますか? + +Express は、\`(path, local, callback) 署名に適合するテンプレートエンジンをサポートしています。 +テンプレートエンジンインターフェイスとキャッシュを正規化するには、 +[consolidate.js](https://github.com/visionmedia/consolidate.js) +プロジェクトをサポートしてください。 リストされていないテンプレートエンジンは引き続きExpress 署名をサポートする可能性があります。 + +詳しくは、[Expressでテンプレートエンジンを使用する](/en/guide/using-template-engines)を参照してください。 + +## 404応答はどのように処理すればいいですか? + +Expressでは404応答はエラーの結果ではないため、 +エラーハンドラミドルウェアはそれらを捕捉しません。 This behavior is +because a 404 response simply indicates the absence of additional work to do; +in other words, Express has executed all middleware functions and routes, +and found that none of them responded. All you need to +do is add a middleware function at the very bottom of the stack (below all other functions) +to handle a 404 response: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +`express.Router()` +のインスタンスで実行時にルートを動的に追加することで、ルートはミドルウェア関数に取って代わられません。 + +## エラーハンドラの設定方法は? + +他のミドルウェアと同じ方法でエラー処理ミドルウェア +を定義します。ただし、3つではなく4つの引数を使用します。 具体的にはシグネチャ`(err, req, res, next)`を指定します。 + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +詳細については、[Error handling](/en/guide/error-handling)を参照してください。 + +## プレーンHTMLをレンダリングするにはどうすればいいですか? + +違います！ `res.render()`関数でHTMLを「レンダリング」する必要はありません。 +特定のファイルがある場合は、 `res.sendFile()` 関数を使用します。 +ディレクトリから多くのアセットを提供している場合は、`express.static()` +ミドルウェア関数を使用してください。 + +## Express にはどのバージョンの Node.js が必要ですか? + +- [Express 4.x](/en/4x/api) では、Node.js 0.10 以上が必要です。 +- Express 5.x](/en/5x/api) ではNode.js 18 以上が必要です。 diff --git a/src/content/docs/ja/5x/starter/generator.mdx b/src/content/docs/ja/5x/starter/generator.mdx new file mode 100644 index 0000000000..308ecf85b6 --- /dev/null +++ b/src/content/docs/ja/5x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Express アプリケーションジェネレーター +description: Expressアプリケーションジェネレータツールを使用して、Express.jsアプリケーション用のスケルトンを迅速に作成し、セットアップと構成を合理化する方法を学びます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +アプリケーションジェネレータツール`express-generator`を使用して、アプリケーションスケルトンを素早く作成します。 + +アプリケーションジェネレータは `npx` コマンド (Node.js 8.2.0で利用可能) で実行できます。 + +```bash +$ npx express-generator +``` + +以前のNodeバージョンの場合は、アプリケーションジェネレータをグローバルnpmパッケージとしてインストールしてから起動します。 + +```bash +$ npm install -g express-generator +$ express +``` + +`-h` オプションでコマンドオプションを表示します。 + +```bash +$ express -h + + Usage: express [options] [dir] + + Options: + + -h, --help output usage information + --version output the version number + -e, --ejs add ejs engine support + --hbs add handlebars engine support + --pug add pug engine support + -H, --hogan add hogan.js engine support + --no-view generate without view engine + -v, --view add view support (ejs|hbs|hjs|jade|pug|twig|vash) (defaults to jade) + -c, --css add stylesheet support (less|stylus|compass|sass) (defaults to plain css) + --git add .gitignore + -f, --force force on non-empty directory +``` + +例えば、次のように、*myapp* という名前の Express アプリケーションを作成します。 アプリは現在の作業ディレクトリの *myapp* というフォルダに作成され、ビューエンジンは Pug に設定されます。 + +```bash +$ express --view=pug myapp + + create : myapp + create : myapp/package.json + create : myapp/app.js + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index.js + create : myapp/routes/users.js + create : myapp/public/stylesheets + create : myapp/public/stylesheets/style.css + create : myapp/views + create : myapp/views/index.pug + create : myapp/views/layout.pug + create : myapp/views/error.pug + create : myapp/bin + create : myapp/bin/www +``` + +次に依存関係をインストール: + +```bash +$ cd myapp +$ npm install +``` + +MacOS または Linux では、次のコマンドでアプリを実行します。 + +```bash +$ DEBUG=myapp:* npm start +``` + +Windows コマンドプロンプトでは、次のコマンドを使用します。 + +```bash +> set DEBUG=myapp:* & npm start +``` + +Windows PowerShell では、次のコマンドを使用します。 + +```bash +PS> $env:DEBUG='myapp:*'; npm start +``` + +次に、ブラウザに`http://localhost:3000/`を読み込んでアプリにアクセスします。 + +生成されたアプリには、次のディレクトリ構造があります。 + +```bash +. +├── app.js +├── bin +│ └── www +├── package.json +├── public +│ ├── images +│ ├── javascripts +│ └── stylesheets +│ └── style.css +├── routes +│ ├── index.js +│ └── users.js +└── views + ├── error.pug + ├── index.pug + └── layout.pug + +7 directories, 9 files +``` + + + +ジェネレータによって作成されたアプリ構造は、Express アプリケーションを構成するための多くの方法の1つに過ぎません。 +自由にこの構造を使用するか、あなたのニーズに最適に変更してください。 + + diff --git a/src/content/docs/ja/5x/starter/hello-world.mdx b/src/content/docs/ja/5x/starter/hello-world.mdx new file mode 100644 index 0000000000..edc332e8bc --- /dev/null +++ b/src/content/docs/ja/5x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Hello world example +description: Express.jsを始めるには、シンプルな「Hello World」アプリケーションを構築しましょう。初心者向けの基本的なセットアップとサーバー作成を説明します。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +以下に埋め込まれているのは、基本的に作成できる最も簡単なExpressアプリです。 It is a single file app +— *not* what you'd get if you use the [Express generator](/en/starter/generator), which +creates the scaffolding for a full app with numerous JavaScript files, Jade templates, and +sub-directories for various purposes. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(port, () => { + console.log(`Example app listening on port ${port}`); +}); +``` + +このアプリはサーバーを起動し、接続のためにポート3000をリッスンします。 アプリはルート URL (`/`) または *route* にリクエスト +を返します。 他のすべてのパスについては、**404 Not Found**で応答します。 + +## ローカルで実行中 + +最初に `myapp` という名前のディレクトリを作成し、変更して `npm init` を実行します。 Then, install `express` as a dependency, as per the [installation guide](/en/starter/installing). + +`myapp` ディレクトリで、`app.js`という名前のファイルを作成し、上の例からコードをコピーします。 + + + +The `req` (request) and `res` (response) are the exact same objects that Node provides, so you can +invoke `req.pipe()`, `req.on('data', callback)`, and anything else you would do without Express +involved. + + + +次のコマンドでアプリを実行します。 + +```bash +$ node app.js +``` + +次に、ブラウザーに `http://localhost:3000/` をロードして出力を確認します。 diff --git a/src/content/docs/ja/5x/starter/installing.mdx b/src/content/docs/ja/5x/starter/installing.mdx new file mode 100644 index 0000000000..ff591af0bb --- /dev/null +++ b/src/content/docs/ja/5x/starter/installing.mdx @@ -0,0 +1,41 @@ +--- +title: インストール中 +description: プロジェクトディレクトリの設定やnpmとの依存関係の管理など、Node.js 環境で Express.js をインストールする方法を学びます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +始める前に、 [Node.js](https://nodejs.org/) 18 以上のインストールがあることを確認してください。 次に、アプリケーションのディレクトリを作成し、その中に移動します。 + +```bash +mkdir myapp +cd myapp +``` + +`npm init` コマンドを使用して、アプリケーション用の `package.json` ファイルを作成します。 +`package.json` がどのように動作するかについては、[npm の package.json handling](https://docs.npmjs.com/files/package.json) を参照してください。 + +```bash +npm init +``` + +このコマンドを実行すると、アプリケーションの名前やバージョンなど、さまざまなものが表示されます。 +今のところ、RETURNを押すと、ほとんどのデフォルトを受け入れることができます。以下の例外があります。 + +``` +エントリ ポイント: (index.js) +``` + +`app.js`、またはメインファイルの名前を何でも入力します。 `index.js`にしたい場合は、RETURNを押して、推奨されるデフォルトのファイル名を受け入れます。 + +次に、Expressを`myapp`ディレクトリにインストールし、依存関係リストに保存します。 例: + +```bash +npm install Express +``` + +Express を一時的にインストールし、依存関係リストに追加しないでください。 + +```bash +npm install express --no-save +``` diff --git a/src/content/docs/ja/5x/starter/static-files.mdx b/src/content/docs/ja/5x/starter/static-files.mdx new file mode 100644 index 0000000000..b72aad560c --- /dev/null +++ b/src/content/docs/ja/5x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Express での静的ファイルの提供 +description: 組み込みの 'static' ミドルウェアを使用して、Express.js アプリケーションで画像、CSS、JavaScript などの静的ファイルを提供する方法を理解します。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +画像、CSSファイル、JavaScriptファイルなどの静的ファイルを提供するには、Express で組み込まれているミドルウェア関数「express.static」を使用します。 + +関数の署名は次のとおりです: + +```js +express.static(root, [options]); +``` + +`root` 引数は、静的アセットを提供するルートディレクトリを指定します。 +引数 `options` の詳細については、 [express.static](/en/5x/api#express.static) を参照してください。 + +例えば、`public`という名前のディレクトリに画像、CSSファイル、JavaScriptファイルを表示するには、次のコードを使用します。 + +```js +app.use(express.static('public')); +``` + +`public` ディレクトリにあるファイルを読み込むことができます。 + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express は静的ディレクトリからの相対的なファイルを検索するので、静的ディレクトリ +の名前は URL の一部ではありません。 + + + +複数の静的アセットディレクトリを使用するには、`express.static` ミドルウェア関数を複数回呼び出します。 + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express は、`express.static` ミドルウェア関数で静的ディレクトリを設定する順序でファイルを検索します。 + + + +For best results, use a reverse +proxy cache to improve performance of +serving static assets. + + + +\`expressで提供されるファイルに対して、仮想パスプレフィックス(ファイルシステム内にパスが実際に存在しない場所)を作成します。 以下に示すように、staticディレクトリの[mount path](/en/5x/api#app.use)を指定します。 + +```js +app.use('/static', express.static('public')); +``` + +`/static` というプレフィックスから、 `public` ディレクトリにあるファイルをロードできます。 + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +しかし、`express.static`関数に与えるパスは、`node`プロセスを起動したディレクトリからの相対パスです。 expressアプリを別のディレクトリから実行する場合、提供したいディレクトリの絶対パスを使用する方が安全です: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public'))); +``` + +`serve-static` 関数とそのオプションの詳細については、 [serve-static](/en/resources/middleware/serve-static) を参照してください。 diff --git a/src/content/docs/ko/4x/advanced/developing-template-engines.md b/src/content/docs/ko/4x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..6e9710fbc5 --- /dev/null +++ b/src/content/docs/ko/4x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Developing template engines for Express +description: Learn how to develop custom template engines for Express.js using app.engine(), with examples on creating and integrating your own template rendering logic. +--- + +Use the `app.engine(ext, callback)` method to create your own template engine. `ext` refers to the file extension, and `callback` is the template engine function, which accepts the following items as parameters: the location of the file, the options object, and the callback function. + +The following code is an example of implementing a very simple template engine for rendering `.ntl` files. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +Your app will now be able to render `.ntl` files. Create a file named `index.ntl` in the `views` directory with the following content. + +```pug +#title# +#message# +``` + +Then, create the following route in your app. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +When you make a request to the home page, `index.ntl` will be rendered as HTML. diff --git a/src/content/docs/ko/4x/guide/behind-proxies.mdx b/src/content/docs/ko/4x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..dc509998f7 --- /dev/null +++ b/src/content/docs/ko/4x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Express behind proxies +description: Learn how to configure Express.js applications to work correctly behind reverse proxies, including using the trust proxy setting to handle client IP addresses. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +When running an Express app behind a reverse proxy, some of the Express APIs may return different values than expected. In order to adjust for this, the `trust proxy` application setting may be used to expose information provided by the reverse proxy in the Express APIs. The most common issue is express APIs that expose the client's IP address may instead show an internal IP address of the reverse proxy. + + + +When configuring the `trust proxy` setting, it is important to understand the exact setup of the +reverse proxy. Since this setting will trust values provided in the request, it is important that +the combination of the setting in Express matches how the reverse proxy operates. + + + +The application setting `trust proxy` may be set to one of the values listed in the following table. + + + + + + + + + + + + + + + + + + + + + +
TypeValue
Boolean +If `true`, the client's IP address is understood as the left-most entry in the `X-Forwarded-For` header. + +If `false`, the app is understood as directly facing the client and the client's IP address is derived from `req.socket.remoteAddress`. This is the default setting. + + +When setting to `true`, it is important to ensure that the last reverse proxy trusted is removing/overwriting all of the following HTTP headers: `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`, otherwise it may be possible for the client to provide any value. + +
IP addresses +An IP address, subnet, or an array of IP addresses and subnets to trust as being a reverse proxy. The following list shows the pre-configured subnet names: + +* loopback - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +You can set IP addresses in any of the following ways: + +```js +app.set('trust proxy', 'loopback'); // specify a single subnet +app.set('trust proxy', 'loopback, 123.123.123.123'); // specify a subnet and an address +app.set('trust proxy', 'loopback, linklocal, uniquelocal'); // specify multiple subnets as CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // specify multiple subnets as an array +``` + +When specified, the IP addresses or the subnets are excluded from the address determination process, and the untrusted IP address nearest to the application server is determined as the client's IP address. This works by checking if `req.socket.remoteAddress` is trusted. If so, then each address in `X-Forwarded-For` is checked from right to left until the first non-trusted address. + +
Number +Use the address that is at most `n` number of hops away from the Express application. `req.socket.remoteAddress` is the first hop, and the rest are looked for in the `X-Forwarded-For` header from right to left. A value of `0` means that the first untrusted address would be `req.socket.remoteAddress`, i.e. there is no reverse proxy. + + +When using this setting, it is important to ensure there are not multiple, different-length paths to the Express application such that the client can be less than the configured number of hops away, otherwise it may be possible for the client to provide any value. + +
Function +Custom trust implementation. + +```js +app.set('trust proxy', (ip) => { + if (ip === '127.0.0.1' || ip === '123.123.123.123') + return true; // trusted IPs + else return false; +}); +``` + +
+ +Enabling `trust proxy` will have the following impact: + +
    +
  • + The value of [req.hostname](/en/api#req.hostname) is derived from the value set in the + `X-Forwarded-Host` header, which can be set by the client or by the proxy. +
    • +
  • + `X-Forwarded-Proto` can be set by the reverse proxy to tell the app whether it is `https` or + `http` or even an invalid name. This value is reflected by [req.protocol](/en/api#req.protocol). +
    • +
  • + The [req.ip](/en/api#req.ip) and [req.ips](/en/api#req.ips) values are populated based on the + socket address and `X-Forwarded-For` header, starting at the first untrusted address. +
    • +
+ +The `trust proxy` setting is implemented using the [proxy-addr](https://www.npmjs.com/package/proxy-addr) package. For more information, see its documentation. diff --git a/src/content/docs/ko/4x/guide/debugging.mdx b/src/content/docs/ko/4x/guide/debugging.mdx new file mode 100644 index 0000000000..a7750f5427 --- /dev/null +++ b/src/content/docs/ko/4x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Debugging Express +description: Learn how to enable and use debugging logs in Express.js applications by setting the DEBUG environment variable for enhanced troubleshooting. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +To see all the internal logs used in Express, set the `DEBUG` environment variable to +`express:*` when launching your app. + +```bash +$ DEBUG=express:* node index.js +``` + +On Windows, use the corresponding command. + +```bash +> $env:DEBUG = "express:*"; node index.js +``` + +Running this command on the default app generated by the [express generator](/en/starter/generator) prints the following output: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +When a request is then made to the app, you will see the logs specified in the Express code: + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index.pug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +To see the logs only from the router implementation, set the value of `DEBUG` to `express:router`. Likewise, to see logs only from the application implementation, set the value of `DEBUG` to `express:application`, and so on. + +## Applications generated by `express` + +An application generated by the `express` command uses the `debug` module and its debug namespace is scoped to the name of the application. + +For example, if you generated the app with `$ express sample-app`, you can enable the debug statements with the following command: + +```bash +$ DEBUG=sample-app:* node ./bin/www +``` + +You can specify more than one debug namespace by assigning a comma-separated list of names: + +```bash +$ DEBUG=http,mail,express:* node index.js +``` + +## Advanced options + +When running through Node.js, you can set a few environment variables that will change the behavior of the debug logging: + +| Name | Purpose | +| ------------------- | ------------------------------------------------- | +| `DEBUG` | Enables/disables specific debugging namespaces. | +| `DEBUG_COLORS` | Whether or not to use colors in the debug output. | +| `DEBUG_DEPTH` | Object inspection depth. | +| `DEBUG_FD` | File descriptor to write debug output to. | +| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. | + + + +The environment variables beginning with `DEBUG_` end up being converted into an Options object +that gets used with `%o`/`%O` formatters. See the Node.js documentation for +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) for the complete +list. + + diff --git a/src/content/docs/ko/4x/guide/error-handling.mdx b/src/content/docs/ko/4x/guide/error-handling.mdx new file mode 100644 index 0000000000..78f1c86e92 --- /dev/null +++ b/src/content/docs/ko/4x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Error Handling +description: Understand how Express.js handles errors in synchronous and asynchronous code, and learn to implement custom error handling middleware for your applications. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Error Handling* refers to how Express catches and processes errors that +occur both synchronously and asynchronously. Express comes with a default error +handler so you don't need to write your own to get started. + +## Catching Errors + +It's important to ensure that Express catches all errors that occur while +running route handlers and middleware. + +Errors that occur in synchronous code inside route handlers and middleware +require no extra work. If synchronous code throws an error, then Express will +catch and process it. For example: + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Express will catch this on its own. +}); +``` + +For errors returned from asynchronous functions invoked by route handlers +and middleware, you must pass them to the `next()` function, where Express will +catch and process them. For example: + +```js +app.get('/', (req, res, next) => { + fs.readFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Pass errors to Express. + } else { + res.send(data); + } + }); +}); +``` + +Starting with Express 5, route handlers and middleware that return a Promise +will call `next(value)` automatically when they reject or throw an error. +For example: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = await getUserById(req.params.id); + res.send(user); +}); +``` + +If `getUserById` throws an error or rejects, `next` will be called with either +the thrown error or the rejected value. If no rejected value is provided, `next` +will be called with a default Error object provided by the Express router. + +If you pass anything to the `next()` function (except the string `'route'`), +Express regards the current request as being an error and will skip any +remaining non-error handling routing and middleware functions. + +If the callback in a sequence provides no data, only errors, you can simplify +this code as follows: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +In the above example, `next` is provided as the callback for `fs.writeFile`, +which is called with or without errors. If there is no error, the second +handler is executed, otherwise Express catches and processes the error. + +You must catch errors that occur in asynchronous code invoked by route handlers or +middleware and pass them to Express for processing. For example: + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + next(err); + } + }, 100); +}); +``` + +The above example uses a `try...catch` block to catch errors in the +asynchronous code and pass them to Express. If the `try...catch` +block were omitted, Express would not catch the error since it is not part of the synchronous +handler code. + +Use promises to avoid the overhead of the `try...catch` block or when using functions +that return promises. For example: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + .then(() => { + throw new Error('BROKEN'); + }) + .catch(next); // Errors will be passed to Express. +}); +``` + +Since promises automatically catch both synchronous errors and rejected promises, +you can simply provide `next` as the final catch handler and Express will catch errors, +because the catch handler is given the error as the first argument. + +You could also use a chain of handlers to rely on synchronous error +catching, by reducing the asynchronous code to something trivial. For example: + +```js +app.get('/', [ + function (req, res, next) { + fs.readFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals.data = data; + next(err); + }); + }, + function (req, res) { + res.locals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +The above example has a couple of trivial statements from the `readFile` +call. If `readFile` causes an error, then it passes the error to Express, otherwise you +quickly return to the world of synchronous error handling in the next handler +in the chain. Then, the example above tries to process the data. If this fails, then the +synchronous error handler will catch it. If you had done this processing inside +the `readFile` callback, then the application might exit and the Express error +handlers would not run. + +Whichever method you use, if you want Express error handlers to be called in and the +application to survive, you must ensure that Express receives the error. + +## The default error handler + +Express comes with a built-in error handler that takes care of any errors that might be encountered in the app. This default error-handling middleware function is added at the end of the middleware function stack. + +If you pass an error to `next()` and you do not handle it in a custom error +handler, it will be handled by the built-in error handler; the error will be +written to the client with the stack trace. The stack trace is not included +in the production environment. + + + +Set the environment variable `NODE_ENV` to `production`, to run the app in production mode. + + + +When an error is written, the following information is added to the +response: + +* The `res.statusCode` is set from `err.status` (or `err.statusCode`). If + this value is outside the 4xx or 5xx range, it will be set to 500. +* The `res.statusMessage` is set according to the status code. +* The body will be the HTML of the status code message when in production + environment, otherwise will be `err.stack`. +* Any headers specified in an `err.headers` object. + +If you call `next()` with an error after you have started writing the +response (for example, if you encounter an error while streaming the +response to the client), the Express default error handler closes the +connection and fails the request. + +So when you add a custom error handler, you must delegate to +the default Express error handler, when the headers +have already been sent to the client: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Note that the default error handler can get triggered if you call `next()` with an error +in your code more than once, even if custom error handling middleware is in place. + +Other error handling middleware can be found at [Express middleware](/en/resources/middleware). + +## Writing error handlers + +Define error-handling middleware functions in the same way as other middleware functions, +except error-handling functions have four arguments instead of three: +`(err, req, res, next)`. For example: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +You define error-handling middleware last, after other `app.use()` and routes calls; for example: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser.urlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app.use(methodOverride()); +app.use((err, req, res, next) => { + // logic +}); +``` + +Responses from within a middleware function can be in any format, such as an HTML error page, a simple message, or a JSON string. + +For organizational (and higher-level framework) purposes, you can define +several error-handling middleware functions, much as you would with +regular middleware functions. For example, to define an error-handler +for requests made by using `XHR` and those without: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser.urlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +In this example, the generic `logErrors` might write request and +error information to `stderr`, for example: + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +Also in this example, `clientErrorHandler` is defined as follows; in this case, the error is explicitly passed along to the next one. + +Notice that when *not* calling "next" in an error-handling function, you are responsible for writing (and ending) the response. Otherwise, those requests will "hang" and will not be eligible for garbage collection. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500).send({ error: 'Something failed!' }); + } else { + next(err); + } +} +``` + +Implement the "catch-all" `errorHandler` function as follows (for example): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +If you have a route handler with multiple callback functions, you can use the `route` parameter to skip to the next route handler. For example: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user.hasPaid) { + // continue handling this request + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent.find((err, doc) => { + if (err) return next(err); + res.json(doc); + }); + } +); +``` + +In this example, the `getPaidContent` handler will be skipped but any remaining handlers in `app` for `/a_route_behind_paywall` would continue to be executed. + + + +Calls to `next()` and `next(err)` indicate that the current handler is complete and in what state. +`next(err)` will skip all remaining handlers in the chain except for those that are set up to +handle errors as described above. + + diff --git a/src/content/docs/ko/4x/guide/overriding-express-api.md b/src/content/docs/ko/4x/guide/overriding-express-api.md new file mode 100644 index 0000000000..f5281a58f5 --- /dev/null +++ b/src/content/docs/ko/4x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Overriding the Express API +description: Discover how to customize and extend the Express.js API by overriding methods and properties on the request and response objects using prototypes. +--- + +The Express API consists of various methods and properties on the request and response objects. These are inherited by prototype. There are two extension points for the Express API: + +1. The global prototypes at `express.request` and `express.response`. +2. App-specific prototypes at `app.request` and `app.response`. + +Altering the global prototypes will affect all loaded Express apps in the same process. If desired, alterations can be made app-specific by only altering the app-specific prototypes after creating a new app. + +## Methods + +You can override the signature and behavior of existing methods with your own, by assigning a custom function. + +Following is an example of overriding the behavior of [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +The above implementation completely changes the original signature of `res.sendStatus`. It now accepts a status code, encoding type, and the message to be sent to the client. + +The overridden method may now be used this way: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## Properties + +Properties in the Express API are either: + +1. Assigned properties (ex: `req.baseUrl`, `req.originalUrl`) +2. Defined as getters (ex: `req.secure`, `req.ip`) + +Since properties under category 1 are dynamically assigned on the `request` and `response` objects in the context of the current request-response cycle, their behavior cannot be overridden. + +Properties under category 2 can be overwritten using the Express API extensions API. + +The following code rewrites how the value of `req.ip` is to be derived. Now, it simply returns the value of the `Client-IP` request header. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Prototype + +In order to provide the Express API, the request/response objects passed to Express (via `app(req, res)`, for example) need to inherit from the same prototype chain. By default, this is `http.IncomingRequest.prototype` for the request and `http.ServerResponse.prototype` for the response. + +Unless necessary, it is recommended that this be done only at the application level, rather than globally. Also, take care that the prototype that is being used matches the functionality as closely as possible to the default prototypes. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/ko/4x/guide/routing.mdx b/src/content/docs/ko/4x/guide/routing.mdx new file mode 100644 index 0000000000..78ab64f6e8 --- /dev/null +++ b/src/content/docs/ko/4x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Routing +description: Learn how to define and use routes in Express.js applications, including route methods, route paths, parameters, and using Router for modular routing. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* refers to how an application's endpoints (URIs) respond to client requests. +For an introduction to routing, see [Basic routing](/en/starter/basic-routing). + +You define routing using methods of the Express `app` object that correspond to HTTP methods; +for example, `app.get()` to handle GET requests and `app.post` to handle POST requests. For a full list, +see [app.METHOD](/en/5x/api#app.METHOD). You can also use [app.all()](/en/5x/api#app.all) to handle all HTTP methods and [app.use()](/en/5x/api#app.use) to +specify middleware as the callback function (See [Using middleware](/en/guide/using-middleware) for details). + +These routing methods specify a callback function (sometimes called "handler functions") called when the application receives a request to the specified route (endpoint) and HTTP method. In other words, the application "listens" for requests that match the specified route(s) and method(s), and when it detects a match, it calls the specified callback function. + +In fact, the routing methods can have more than one callback function as arguments. +With multiple callback functions, it is important to provide `next` as an argument to the callback function and then call `next()` within the body of the function to hand off control +to the next callback. + +The following code is an example of a very basic route. + +```js +const express = require('express'); +const app = express(); + +// respond with "hello world" when a GET request is made to the homepage +app.get('/', (req, res) => { + res.send('hello world'); +}); +``` + +## Route methods + +A route method is derived from one of the HTTP methods, and is attached to an instance of the `express` class. + +The following code is an example of routes that are defined for the `GET` and the `POST` methods to the root of the app. + +```js +// GET method route +app.get('/', (req, res) => { + res.send('GET request to the homepage'); +}); + +// POST method route +app.post('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Express supports methods that correspond to all HTTP request methods: `get`, `post`, and so on. +For a full list, see [app.METHOD](/en/5x/api#app.METHOD). + +There is a special routing method, `app.all()`, used to load middleware functions at a path for *all* HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Accessing the secret section ...'); + next(); // pass control to the next handler +}); +``` + +## Route paths + +Route paths, in combination with a request method, define the endpoints at which requests can be made. Route paths can be strings, string patterns, or regular expressions. + + + +In express 5, the characters `?`, `+`, `*`, `[]`, and `()` are handled differently than in version +4, please review the [migration guide](/en/guide/migrating-5#path-syntax) for more information. + + + + + +In express 4, regular expression characters such as `$` need to be escaped with a `\`. + + + + + +Express uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) for matching the route +paths; see the path-to-regexp documentation for all the possibilities in defining route paths. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) is a handy tool for +testing basic Express routes, although it does not support pattern matching. + + + +Query strings are not part of the route path. + +### Route paths based on strings + +This route path will match requests to the root route, `/`. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +This route path will match requests to `/about`. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +This route path will match requests to `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Route paths based on string patterns + + + +The string patterns in Express 5 no longer work. Please refer to the migration +guide for more information. + + + +This route path will match `acd` and `abcd`. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +This route path will match `abcd`, `abbcd`, `abbbcd`, and so on. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +This route path will match `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd`, and so on. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +This route path will match `/abe` and `/abcde`. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Route paths based on regular expressions + +This route path will match anything with an "a" in it. + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +This route path will match `butterfly` and `dragonfly`, but not `butterflyman`, `dragonflyman`, and so on. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Route parameters + +Route parameters are named URL segments that are used to capture the values specified at their position in the URL. The captured values are populated in the `req.params` object, with the name of the route parameter specified in the path as their respective keys. + +``` +Route path: /users/:userId/books/:bookId +Request URL: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +To define routes with route parameters, simply specify the route parameters in the path of the route as shown below. + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +The name of route parameters must be made up of "word characters" ([A-Za-z0-9_]). + + + +Since the hyphen (`-`) and the dot (`.`) are interpreted literally, they can be used along with route parameters for useful purposes. + +``` +Route path: /flights/:from-:to +Request URL: http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Route path: /plantae/:genus.:species +Request URL: http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +In express 5, Regexp characters are not supported in route paths, for more information please +refer to the [migration guide](/en/guide/migrating-5#path-syntax). + + + +To have more control over the exact string that can be matched by a route parameter, you can append a regular expression in parentheses (`()`): + +``` +Route path: /user/:userId(\d+) +Request URL: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Because the regular expression is usually part of a literal string, be sure to escape any `\` +characters with an additional backslash, for example `\d+`. + + + + +In Express 4.x, the `*` character in regular expressions is not interpreted in the usual way. As a workaround, use `{0,}` instead of `*`. This will likely be fixed in Express 5. + + +## Route handlers + +You can provide multiple callback functions that behave like [middleware](/en/guide/using-middleware) to handle a request. The only exception is that these callbacks might invoke `next('route')` to bypass the remaining route callbacks. You can use this mechanism to impose pre-conditions on a route, then pass control to subsequent routes if there's no reason to proceed with the current route. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params.id === '0') { + return next('route'); + } + res.send(`User ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Special handler for user ID 0'); +}); +``` + +In this example: + +* `GET /user/5` → handled by first route → sends "User 5" +* `GET /user/0` → first route calls `next('route')`, skipping to the next matching `/user/:id` route + +Route handlers can be in the form of a function, an array of functions, or combinations of both, as shown in the following examples. + +A single callback function can handle a route. For example: + +```js +app.get('/example/a', (req, res) => { + res.send('Hello from A!'); +}); +``` + +More than one callback function can handle a route (make sure you specify the `next` object). For example: + +```js +app.get( + '/example/b', + (req, res, next) => { + console.log('the response will be sent by the next function ...'); + next(); + }, + (req, res) => { + res.send('Hello from B!'); + } +); +``` + +An array of callback functions can handle a route. For example: + +```js +const cb0 = function (req, res, next) { + console.log('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console.log('CB1'); + next(); +}; + +const cb2 = function (req, res) { + res.send('Hello from C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +A combination of independent functions and arrays of functions can handle a route. For example: + +```js +const cb0 = function (req, res, next) { + console.log('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console.log('CB1'); + next(); +}; + +app.get( + '/example/d', + [cb0, cb1], + (req, res, next) => { + console.log('the response will be sent by the next function ...'); + next(); + }, + (req, res) => { + res.send('Hello from D!'); + } +); +``` + +## Response methods + +The methods on the response object (`res`) in the following table can send a response to the client, and terminate the request-response cycle. If none of these methods are called from a route handler, the client request will be left hanging. + +| Method | Description | +| --------------------------------------------- | ------------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | Prompt a file to be downloaded. | +| [res.end()](/en/5x/api#res.end) | End the response process. | +| [res.json()](/en/5x/api#res.json) | Send a JSON response. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Send a JSON response with JSONP support. | +| [res.redirect()](/en/5x/api#res.redirect) | Redirect a request. | +| [res.render()](/en/5x/api#res.render) | Render a view template. | +| [res.send()](/en/5x/api#res.send) | Send a response of various types. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Send a file as an octet stream. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Set the response status code and send its string representation as the response body. | + +## app.route() + +You can create chainable route handlers for a route path by using `app.route()`. +Because the path is specified at a single location, creating modular routes is helpful, as is reducing redundancy and typos. For more information about routes, see: [Router() documentation](/en/5x/api#router). + +Here is an example of chained route handlers that are defined by using `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res.send('Get a random book'); + }) + .post((req, res) => { + res.send('Add a book'); + }) + .put((req, res) => { + res.send('Update the book'); + }); +``` + +## express.Router + +Use the `express.Router` class to create modular, mountable route handlers. A `Router` instance is a complete middleware and routing system; for this reason, it is often referred to as a "mini-app". + +The following example creates a router as a module, loads a middleware function in it, defines some routes, and mounts the router module on a path in the main app. + +Create a router file named `birds.js` in the app directory, with the following content: + +```js +const express = require('express'); +const router = express.Router(); + +// middleware that is specific to this router +const timeLog = (req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}; +router.use(timeLog); + +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Then, load the router module in the app: + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +The app will now be able to handle requests to `/birds` and `/birds/about`, as well as call the `timeLog` middleware function that is specific to the route. + +But if the parent route `/birds` has path parameters, it will not be accessible by default from the sub-routes. To make it accessible, you will need to pass the `mergeParams` option to the Router constructor [reference](/en/5x/api#app.use). + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/ko/4x/guide/using-middleware.mdx b/src/content/docs/ko/4x/guide/using-middleware.mdx new file mode 100644 index 0000000000..026542a234 --- /dev/null +++ b/src/content/docs/ko/4x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Using middleware +description: Learn how to use middleware in Express.js applications, including application-level and router-level middleware, error handling, and integrating third-party middleware. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express is a routing and middleware web framework that has minimal functionality of its own: An Express application is essentially a series of middleware function calls. + +*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. + +Middleware functions can perform the following tasks: + +* Execute any code. +* Make changes to the request and the response objects. +* End the request-response cycle. +* Call the next middleware function in the stack. + +If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. + +An Express application can use the following types of middleware: + +* [Application-level middleware](#middleware.application) +* [Router-level middleware](#middleware.router) +* [Error-handling middleware](#middleware.error-handling) +* [Built-in middleware](#middleware.built-in) +* [Third-party middleware](#middleware.third-party) + +You can load application-level and router-level middleware with an optional mount path. +You can also load a series of middleware functions together, which creates a sub-stack of the middleware system at a mount point. + +## Application-level middleware + +Bind application-level middleware to an instance of the [app object](/en/5x/api#app) by using the `app.use()` and `app.METHOD()` functions, where `METHOD` is the HTTP method of the request that the middleware function handles (such as GET, PUT, or POST) in lowercase. + +This example shows a middleware function with no mount path. The function is executed every time the app receives a request. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +This example shows a middleware function mounted on the `/user/:id` path. The function is executed for any type of +HTTP request on the `/user/:id` path. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +This example shows a route and its handler function (middleware system). The function handles GET requests to the `/user/:id` path. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +Here is an example of loading a series of middleware functions at a mount point, with a mount path. +It illustrates a middleware sub-stack that prints request info for any type of HTTP request to the `/user/:id` path. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); +``` + +Route handlers enable you to define multiple routes for a path. The example below defines two routes for GET requests to the `/user/:id` path. The second route will not cause any problems, but it will never get called because the first route ends the request-response cycle. + +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req.params.id); + next(); + }, + (req, res, next) => { + res.send('User Info'); + } +); + +// handler for the /user/:id path, which prints the user ID +app.get('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +To skip the rest of the middleware functions from a router middleware stack, call `next('route')` to pass control to the next route. + + + +`next('route')` will work only in middleware functions that were loaded by using the +`app.METHOD()` or `router.METHOD()` functions. + + + +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. + +```js +app.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next route + if (req.params.id === '0') next('route'); + // otherwise pass the control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // send a regular response + res.send('regular'); + } +); + +// handler for the /user/:id path, which sends a special response +app.get('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +Middleware can also be declared in an array for reusability. + +This example shows an array with a middleware sub-stack that handles GET requests to the `/user/:id` path + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req.originalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Request Type:', req.method); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app.get('/user/:id', logStuff, (req, res, next) => { + res.send('User Info'); +}); +``` + +## Router-level middleware + +Router-level middleware works in the same way as application-level middleware, except it is bound to an instance of `express.Router()`. + +```js +const router = express.Router(); +``` + +Load router-level middleware by using the `router.use()` and `router.METHOD()` functions. + +The following example code replicates the middleware system that is shown above for application-level middleware, by using router-level middleware: + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// a middleware function with no mount path. This code is executed for every request to the router +router.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); + +// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path +router.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); + +// a middleware sub-stack that handles GET requests to the /user/:id path +router.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next router + if (req.params.id === '0') next('route'); + // otherwise pass control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // render a regular page + res.render('regular'); + } +); + +// handler for the /user/:id path, which renders a special page +router.get('/user/:id', (req, res, next) => { + console.log(req.params.id); + res.render('special'); +}); + +// mount the router on the app +app.use('/', router); +``` + +To skip the rest of the router's middleware functions, call `next('router')` +to pass control back out of the router instance. + +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// predicate the router with a check and bail out when needed +router.use((req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router.get('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// use the router and 401 anything falling through +app.use('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## Error-handling middleware + + + +Error-handling middleware always takes *four* arguments. You must provide four arguments to +identify it as an error-handling middleware function. Even if you don't need to use the `next` +object, you must specify it to maintain the signature. Otherwise, the `next` object will be +interpreted as regular middleware and will fail to handle errors. + + + +Define error-handling middleware functions in the same way as other middleware functions, except with four arguments instead of three, specifically with the signature `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +For details about error-handling middleware, see: [Error handling](/en/guide/error-handling). + +## Built-in middleware + +Starting with version 4.x, Express no longer depends on [Connect](https://github.com/senchalabs/connect). The middleware +functions that were previously included with Express are now in separate modules; see [the list of middleware functions](https://github.com/senchalabs/connect#middleware). + +Express has the following built-in middleware functions: + +* [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. +* [express.json](/en/5x/api#express.json) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** + +## Third-party middleware + +Use third-party middleware to add functionality to Express apps. + +Install the Node.js module for the required functionality, then load it in your app at the application level or at the router level. + +The following example illustrates installing and loading the cookie-parsing middleware function `cookie-parser`. + +```bash +$ npm install cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// load the cookie-parsing middleware +app.use(cookieParser()); +``` + +For a partial list of third-party middleware functions that are commonly used with Express, see: [Third-party middleware](../resources/middleware). diff --git a/src/content/docs/ko/4x/guide/using-template-engines.mdx b/src/content/docs/ko/4x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..7095bc6dd5 --- /dev/null +++ b/src/content/docs/ko/4x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Using template engines with Express +description: Discover how to integrate and use template engines like Pug, Handlebars, and EJS with Express.js to render dynamic HTML pages efficiently. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +A *template engine* enables you to use static template files in your application. At runtime, the template engine replaces +variables in a template file with actual values, and transforms the template into an HTML file sent to the client. +This approach makes it easier to design an HTML page. + +The [Express application generator](/en/starter/generator) uses [Pug](https://pugjs.org/api/getting-started.html) as its default, but it also supports [Handlebars](https://www.npmjs.com/package/handlebars), and [EJS](https://www.npmjs.com/package/ejs), among others. + +To render template files, set the following [application setting properties](/en/4x/api#app.set), in the default `app.js` created by the generator: + +* `views`, the directory where the template files are located. Eg: `app.set('views', './views')`. + This defaults to the `views` directory in the application root directory. +* `view engine`, the template engine to use. For example, to use the Pug template engine: `app.set('view engine', 'pug')`. + +Then install the corresponding template engine npm package; for example to install Pug: + +```bash +$ npm install pug --save +``` + + +Express-compliant template engines such as Pug export a function named `__express(filePath, options, callback)`, +which `res.render()` calls to render the template code. + +Some template engines do not follow this convention. The [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +library follows this convention by mapping all of the popular Node.js template engines, and therefore works seamlessly within Express. + + + +After the view engine is set, you don't have to specify the engine or load the template engine module in your app; +Express loads the module internally, for example: + +```js +app.set('view engine', 'pug'); +``` + +Then, create a Pug template file named `index.pug` in the `views` directory, with the following content: + +```pug +html + head + title= title + body + h1= message +``` + +Create a route to render the `index.pug` file. If the `view engine` property is not set, +you must specify the extension of the `view` file. Otherwise, you can omit it. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +When you make a request to the home page, the `index.pug` file will be rendered as HTML. + +The view engine cache does not cache the contents of the template's output, only the underlying template itself. The view is still re-rendered with every request even when the cache is on. diff --git a/src/content/docs/ko/4x/guide/writing-middleware.mdx b/src/content/docs/ko/4x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..355028e8b0 --- /dev/null +++ b/src/content/docs/ko/4x/guide/writing-middleware.mdx @@ -0,0 +1,239 @@ +--- +title: Writing middleware for use in Express apps +description: Learn how to write custom middleware functions for Express.js applications, including examples and best practices for enhancing request and response handling. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. + +Middleware functions can perform the following tasks: + +* Execute any code. +* Make changes to the request and the response objects. +* End the request-response cycle. +* Call the next middleware in the stack. + +If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. + +The following figure shows the elements of a middleware function call: + +
+ + + + + +
+Elements of a middleware function call + +
HTTP method for which the middleware function applies.
+ +
+ Path (route) for which the middleware function applies. +
+ +
+ The middleware function. +
+ +
+ Callback argument to the middleware function, called "next" by convention. +
+ +
+ HTTP response argument to the middleware function, called "res" by + convention. +
+ +
HTTP request argument to the middleware function, called "req" by convention.
+
+
+ +Starting with Express 5, middleware functions that return a Promise will call `next(value)` when they reject or throw an error. `next` will be called with either the rejected value or the thrown Error. + +## Example + +Here is an example of a simple "Hello World" Express application. +The remainder of this article will define and add three middleware functions to the application: +one called `myLogger` that prints a simple log message, one called `requestTime` that +displays the timestamp of the HTTP request, and one called `validateCookies` that validates incoming cookies. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +### Middleware function myLogger + +Here is a simple example of a middleware function called "myLogger". This function just prints +"LOGGED" when a request to the app passes through it. The middleware function is assigned to a +variable named `myLogger`. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +Notice the call above to `next()`. Calling this function invokes the next middleware function in +the app. The `next()` function is not a part of the Node.js or Express API, but is the third +argument that is passed to the middleware function. The `next()` function could be named anything, +but by convention it is always named "next". To avoid confusion, always use this convention. + + + +To load the middleware function, call `app.use()`, specifying the middleware function. +For example, the following code loads the `myLogger` middleware function before the route to the root path (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +Every time the app receives a request, it prints the message "LOGGED" to the terminal. + +The order of middleware loading is important: middleware functions that are loaded first are also executed first. + +If `myLogger` is loaded after the route to the root path, the request never reaches it and the app doesn't print "LOGGED", because the route handler of the root path terminates the request-response cycle. + +The middleware function `myLogger` simply prints a message, then passes on the request to the next middleware function in the stack by calling the `next()` function. + +### Middleware function requestTime + +Next, we'll create a middleware function called "requestTime" and add a property called `requestTime` +to the request object. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +The app now uses the `requestTime` middleware function. Also, the callback function of the root path route uses the property that the middleware function adds to `req` (the request object). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app.get('/', (req, res) => { + let responseText = 'Hello World!
'; + responseText += `Requested at: ${req.requestTime}`; + res.send(responseText); +}); + +app.listen(3000); +``` + +When you make a request to the root of the app, the app now displays the timestamp of your request in the browser. + +### Middleware function validateCookies + +Finally, we'll create a middleware function that validates incoming cookies and sends a 400 response if cookies are invalid. + +Here's an example function that validates cookies with an external async service. + +```js +async function cookieValidator(cookies) { + try { + await externallyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Invalid cookies'); + } +} +``` + +Here, we use the [`cookie-parser`](/en/resources/middleware/cookie-parser) middleware to parse incoming cookies off the `req` object and pass them to our `cookieValidator` function. The `validateCookies` middleware returns a Promise that upon rejection will automatically trigger our error handler. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('./cookieValidator'); + +const app = express(); + +async function validateCookies(req, res, next) { + await cookieValidator(req.cookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// error handler +app.use((err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Note how `next()` is called after `await cookieValidator(req.cookies)`. This ensures that if +`cookieValidator` resolves, the next middleware in the stack will get called. If you pass anything +to the `next()` function (except the string `'route'` or `'router'`), Express regards the current +request as being an error and will skip any remaining non-error handling routing and middleware +functions. + + + +Because you have access to the request object, the response object, the next middleware function in the stack, and the whole Node.js API, the possibilities with middleware functions are endless. + +For more information about Express middleware, see: [Using Express middleware](/en/guide/using-middleware). + +## Configurable middleware + +If you need your middleware to be configurable, export a function which accepts an options object or other parameters, which, then returns the middleware implementation based on the input parameters. + +File: `my-middleware.js` + +```js +module.exports = function (options) { + return function (req, res, next) { + // Implement the middleware function based on the options object + next(); + }; +}; +``` + +The middleware can now be used as shown below. + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Refer to [cookie-session](https://github.com/expressjs/cookie-session) and [compression](https://github.com/expressjs/compression) for examples of configurable middleware. diff --git a/src/content/docs/ko/4x/starter/basic-routing.mdx b/src/content/docs/ko/4x/starter/basic-routing.mdx new file mode 100644 index 0000000000..35d674808b --- /dev/null +++ b/src/content/docs/ko/4x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Basic routing +description: Learn the fundamentals of routing in Express.js applications, including how to define routes, handle HTTP methods, and create route handlers for your web server. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). + +Each route can have one or more handler functions, which are executed when the route is matched. + +Route definition takes the following structure: + +```js +app.METHOD(PATH, HANDLER); +``` + +Where: + +* `app` is an instance of `express`. +* `METHOD` is an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in lowercase. +* `PATH` is a path on the server. +* `HANDLER` is the function executed when the route is matched. + + + +This tutorial assumes that an instance of `express` named `app` is created and the server is +running. If you are not familiar with creating an app and starting it, see the Hello world +example. + + + +The following examples illustrate defining simple routes. + +Respond with `Hello World!` on the homepage: + +```js +app.get('/', (req, res) => { + res.send('Hello World!'); +}); +``` + +Respond to a POST request on the root route (`/`), the application's home page: + +```js +app.post('/', (req, res) => { + res.send('Got a POST request'); +}); +``` + +Respond to a PUT request to the `/user` route: + +```js +app.put('/user', (req, res) => { + res.send('Got a PUT request at /user'); +}); +``` + +Respond to a DELETE request to the `/user` route: + +```js +app.delete('/user', (req, res) => { + res.send('Got a DELETE request at /user'); +}); +``` + +For more details about routing, see the [routing guide](/en/guide/routing). diff --git a/src/content/docs/ko/4x/starter/examples.mdx b/src/content/docs/ko/4x/starter/examples.mdx new file mode 100644 index 0000000000..4135b751cd --- /dev/null +++ b/src/content/docs/ko/4x/starter/examples.mdx @@ -0,0 +1,45 @@ +--- +title: Express examples +description: Explore a collection of Express.js application examples covering various use cases, integrations, and advanced configurations to help you learn and build your projects. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Authentication with login and password +* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - HTTP content negotiation +* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Working with cookie-based sessions +* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Working with cookies +* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transferring files to client +* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Working with Embedded JavaScript templating (ejs) +* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Creating error pages +* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Working with error middleware +* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Simple request handler +* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown as template engine +* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Working with multiple Express routers +* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - MVC-style controllers +* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Tracking online user activity with `online` and `redis` packages +* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Working with route parameters +* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Multiple HTTP operations on the same resource +* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organizing routes using a map +* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Working with route middleware +* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizing routes per each resource +* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Search API +* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - User sessions +* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Serving static files +* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Working with virtual hosts +* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Rendering views dynamically +* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Saving data in request object between middleware calls +* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Simple API service + +## Additional examples + +These are some additional examples with more extensive integrations. + + + This information refers to third-party sites, products, or modules that are not maintained by the + Expressjs team. Listing here does not constitute an endorsement or recommendation from the + Expressjs project team. + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app with Express and Next.js using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM diff --git a/src/content/docs/ko/4x/starter/faq.md b/src/content/docs/ko/4x/starter/faq.md new file mode 100644 index 0000000000..1adcb7be0e --- /dev/null +++ b/src/content/docs/ko/4x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: FAQ +description: Find answers to frequently asked questions about Express.js, including topics on application structure, models, authentication, template engines, error handling, and more. +--- + +## How should I structure my application? + +There is no definitive answer to this question. The answer depends +on the scale of your application and the team that is involved. To be as +flexible as possible, Express makes no assumptions in terms of structure. + +Routes and other application-specific logic can live in as many files +as you wish, in any directory structure you prefer. View the following +examples for inspiration: + +- [Route listings](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Route map](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Also, there are third-party extensions for Express, which simplify some of these patterns: + +- [Resourceful routing](https://github.com/expressjs/express-resource) + +## How do I define models? + +Express has no notion of a database. This concept is +left up to third-party Node modules, allowing you to +interface with nearly any database. + +See [LoopBack](http://loopback.io) for an Express-based framework that is centered around models. + +## How can I authenticate users? + +Authentication is another opinionated area that Express does not +venture into. You may use any authentication scheme you wish. +For a simple username / password scheme, see [this example](https://github.com/expressjs/express/tree/master/examples/auth). + +## Which template engines does Express support? + +Express supports any template engine that conforms with the `(path, locals, callback)` signature. +To normalize template engine interfaces and caching, see the +[consolidate.js](https://github.com/visionmedia/consolidate.js) +project for support. Unlisted template engines might still support the Express signature. + +For more information, see [Using template engines with Express](/en/guide/using-template-engines). + +## How do I handle 404 responses? + +In Express, 404 responses are not the result of an error, so +the error-handler middleware will not capture them. This behavior is +because a 404 response simply indicates the absence of additional work to do; +in other words, Express has executed all middleware functions and routes, +and found that none of them responded. All you need to +do is add a middleware function at the very bottom of the stack (below all other functions) +to handle a 404 response: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Add routes dynamically at runtime on an instance of `express.Router()` +so the routes are not superseded by a middleware function. + +## How do I setup an error handler? + +You define error-handling middleware in the same way as other middleware, +except with four arguments instead of three; specifically with the signature `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +For more information, see [Error handling](/en/guide/error-handling). + +## How do I render plain HTML? + +You don't! There's no need to "render" HTML with the `res.render()` function. +If you have a specific file, use the `res.sendFile()` function. +If you are serving many assets from a directory, use the `express.static()` +middleware function. + +## What version of Node.js does Express require? + +- [Express 4.x](/en/4x/api) requires Node.js 0.10 or higher. +- [Express 5.x](/en/5x/api) requires Node.js 18 or higher. diff --git a/src/content/docs/ko/4x/starter/generator.mdx b/src/content/docs/ko/4x/starter/generator.mdx new file mode 100644 index 0000000000..859bec927e --- /dev/null +++ b/src/content/docs/ko/4x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Express application generator +description: Learn how to use the Express application generator tool to quickly create a skeleton for your Express.js applications, streamlining setup and configuration. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Use the application generator tool, `express-generator`, to quickly create an application skeleton. + +You can run the application generator with the `npx` command (available in Node.js 8.2.0). + +```bash +$ npx express-generator +``` + +For earlier Node versions, install the application generator as a global npm package and then launch it: + +```bash +$ npm install -g express-generator +$ express +``` + +Display the command options with the `-h` option: + +```bash +$ express -h + + Usage: express [options] [dir] + + Options: + + -h, --help output usage information + --version output the version number + -e, --ejs add ejs engine support + --hbs add handlebars engine support + --pug add pug engine support + -H, --hogan add hogan.js engine support + --no-view generate without view engine + -v, --view add view support (ejs|hbs|hjs|jade|pug|twig|vash) (defaults to jade) + -c, --css add stylesheet support (less|stylus|compass|sass) (defaults to plain css) + --git add .gitignore + -f, --force force on non-empty directory +``` + +For example, the following creates an Express app named *myapp*. The app will be created in a folder named *myapp* in the current working directory and the view engine will be set to Pug: + +```bash +$ express --view=pug myapp + + create : myapp + create : myapp/package.json + create : myapp/app.js + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index.js + create : myapp/routes/users.js + create : myapp/public/stylesheets + create : myapp/public/stylesheets/style.css + create : myapp/views + create : myapp/views/index.pug + create : myapp/views/layout.pug + create : myapp/views/error.pug + create : myapp/bin + create : myapp/bin/www +``` + +Then install dependencies: + +```bash +$ cd myapp +$ npm install +``` + +On MacOS or Linux, run the app with this command: + +```bash +$ DEBUG=myapp:* npm start +``` + +On Windows Command Prompt, use this command: + +```bash +> set DEBUG=myapp:* & npm start +``` + +On Windows PowerShell, use this command: + +```bash +PS> $env:DEBUG='myapp:*'; npm start +``` + +Then, load `http://localhost:3000/` in your browser to access the app. + +The generated app has the following directory structure: + +```bash +. +├── app.js +├── bin +│ └── www +├── package.json +├── public +│ ├── images +│ ├── javascripts +│ └── stylesheets +│ └── style.css +├── routes +│ ├── index.js +│ └── users.js +└── views + ├── error.pug + ├── index.pug + └── layout.pug + +7 directories, 9 files +``` + + + +The app structure created by the generator is just one of many ways to structure Express apps. +Feel free to use this structure or modify it to best suit your needs. + + diff --git a/src/content/docs/ko/4x/starter/hello-world.mdx b/src/content/docs/ko/4x/starter/hello-world.mdx new file mode 100644 index 0000000000..d92beecd0a --- /dev/null +++ b/src/content/docs/ko/4x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Hello world example +description: Get started with Express.js by building a simple 'Hello World' application, demonstrating the basic setup and server creation for beginners. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Embedded below is essentially the simplest Express app you can create. It is a single file app +— *not* what you'd get if you use the [Express generator](/en/starter/generator), which +creates the scaffolding for a full app with numerous JavaScript files, Jade templates, and +sub-directories for various purposes. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(port, () => { + console.log(`Example app listening on port ${port}`); +}); +``` + +This app starts a server and listens on port 3000 for connections. The app responds with "Hello World!" for requests +to the root URL (`/`) or *route*. For every other path, it will respond with a **404 Not Found**. + +## Running Locally + +First create a directory named `myapp`, change to it and run `npm init`. Then, install `express` as a dependency, as per the [installation guide](/en/starter/installing). + +In the `myapp` directory, create a file named `app.js` and copy the code from the example above. + + + +The `req` (request) and `res` (response) are the exact same objects that Node provides, so you can +invoke `req.pipe()`, `req.on('data', callback)`, and anything else you would do without Express +involved. + + + +Run the app with the following command: + +```bash +$ node app.js +``` + +Then, load `http://localhost:3000/` in a browser to see the output. diff --git a/src/content/docs/ko/4x/starter/installing.mdx b/src/content/docs/ko/4x/starter/installing.mdx new file mode 100644 index 0000000000..fc66c7f9df --- /dev/null +++ b/src/content/docs/ko/4x/starter/installing.mdx @@ -0,0 +1,50 @@ +--- +title: Installing +description: Learn how to install Express.js in your Node.js environment, including setting up your project directory and managing dependencies with npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Before you begin, make sure you have [Node.js](https://nodejs.org/) 0.10 or higher installed. Then, create a directory for your application and navigate into it. + +```bash +mkdir myapp +cd myapp +``` + +Use the `npm init` command to create a `package.json` file for your application. +For more information on how `package.json` works, see [Specifics of npm's package.json handling](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +This command prompts you for a number of things, such as the name and version of your application. +For now, you can simply hit RETURN to accept the defaults for most of them, with the following exception: + +``` +entry point: (index.js) +``` + +Enter `app.js`, or whatever you want the name of the main file to be. If you want it to be `index.js`, hit RETURN to accept the suggested default file name. + +Now, install Express in the `myapp` directory and save it in the dependencies list. For example: + +```bash +npm install express +``` + +To install Express temporarily and not add it to the dependencies list: + +```bash +npm install express --no-save +``` + + + +By default with version npm 5.0+, `npm install` adds the module to the `dependencies` list in the +`package.json` file; with earlier versions of npm, you must specify the `--save` option +explicitly. Then, afterwards, running `npm install` in the app directory will automatically +install modules in the dependencies list. + + diff --git a/src/content/docs/ko/4x/starter/static-files.mdx b/src/content/docs/ko/4x/starter/static-files.mdx new file mode 100644 index 0000000000..98855e0d05 --- /dev/null +++ b/src/content/docs/ko/4x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Serving static files in Express +description: Understand how to serve static files like images, CSS, and JavaScript in Express.js applications using the built-in 'static' middleware. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +To serve static files such as images, CSS files, and JavaScript files, use the `express.static` built-in middleware function in Express. + +The function signature is: + +```js +express.static(root, [options]); +``` + +The `root` argument specifies the root directory from which to serve static assets. +For more information on the `options` argument, see [express.static](/en/5x/api#express.static). + +For example, use the following code to serve images, CSS files, and JavaScript files in a directory named `public`: + +```js +app.use(express.static('public')); +``` + +Now, you can load the files that are in the `public` directory: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express looks up the files relative to the static directory, so the name of the static directory +is not part of the URL. + + + +To use multiple static assets directories, call the `express.static` middleware function multiple times: + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express looks up the files in the order in which you set the static directories with the `express.static` middleware function. + + + +For best results, use a reverse +proxy cache to improve performance of +serving static assets. + + + +To create a virtual path prefix (where the path does not actually exist in the file system) for files that are served by the `express.static` function, [specify a mount path](/en/5x/api#app.use) for the static directory, as shown below: + +```js +app.use('/static', express.static('public')); +``` + +Now, you can load the files that are in the `public` directory from the `/static` path prefix. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +However, the path that you provide to the `express.static` function is relative to the directory from where you launch your `node` process. If you run the express app from another directory, it's safer to use the absolute path of the directory that you want to serve: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public'))); +``` + +For more details about the `serve-static` function and its options, see [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/ko/5x/advanced/developing-template-engines.md b/src/content/docs/ko/5x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..6e9710fbc5 --- /dev/null +++ b/src/content/docs/ko/5x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Developing template engines for Express +description: Learn how to develop custom template engines for Express.js using app.engine(), with examples on creating and integrating your own template rendering logic. +--- + +Use the `app.engine(ext, callback)` method to create your own template engine. `ext` refers to the file extension, and `callback` is the template engine function, which accepts the following items as parameters: the location of the file, the options object, and the callback function. + +The following code is an example of implementing a very simple template engine for rendering `.ntl` files. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +Your app will now be able to render `.ntl` files. Create a file named `index.ntl` in the `views` directory with the following content. + +```pug +#title# +#message# +``` + +Then, create the following route in your app. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +When you make a request to the home page, `index.ntl` will be rendered as HTML. diff --git a/src/content/docs/ko/5x/guide/behind-proxies.mdx b/src/content/docs/ko/5x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..dc509998f7 --- /dev/null +++ b/src/content/docs/ko/5x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Express behind proxies +description: Learn how to configure Express.js applications to work correctly behind reverse proxies, including using the trust proxy setting to handle client IP addresses. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +When running an Express app behind a reverse proxy, some of the Express APIs may return different values than expected. In order to adjust for this, the `trust proxy` application setting may be used to expose information provided by the reverse proxy in the Express APIs. The most common issue is express APIs that expose the client's IP address may instead show an internal IP address of the reverse proxy. + + + +When configuring the `trust proxy` setting, it is important to understand the exact setup of the +reverse proxy. Since this setting will trust values provided in the request, it is important that +the combination of the setting in Express matches how the reverse proxy operates. + + + +The application setting `trust proxy` may be set to one of the values listed in the following table. + + + + + + + + + + + + + + + + + + + + + +
TypeValue
Boolean +If `true`, the client's IP address is understood as the left-most entry in the `X-Forwarded-For` header. + +If `false`, the app is understood as directly facing the client and the client's IP address is derived from `req.socket.remoteAddress`. This is the default setting. + + +When setting to `true`, it is important to ensure that the last reverse proxy trusted is removing/overwriting all of the following HTTP headers: `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`, otherwise it may be possible for the client to provide any value. + +
IP addresses +An IP address, subnet, or an array of IP addresses and subnets to trust as being a reverse proxy. The following list shows the pre-configured subnet names: + +* loopback - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +You can set IP addresses in any of the following ways: + +```js +app.set('trust proxy', 'loopback'); // specify a single subnet +app.set('trust proxy', 'loopback, 123.123.123.123'); // specify a subnet and an address +app.set('trust proxy', 'loopback, linklocal, uniquelocal'); // specify multiple subnets as CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // specify multiple subnets as an array +``` + +When specified, the IP addresses or the subnets are excluded from the address determination process, and the untrusted IP address nearest to the application server is determined as the client's IP address. This works by checking if `req.socket.remoteAddress` is trusted. If so, then each address in `X-Forwarded-For` is checked from right to left until the first non-trusted address. + +
Number +Use the address that is at most `n` number of hops away from the Express application. `req.socket.remoteAddress` is the first hop, and the rest are looked for in the `X-Forwarded-For` header from right to left. A value of `0` means that the first untrusted address would be `req.socket.remoteAddress`, i.e. there is no reverse proxy. + + +When using this setting, it is important to ensure there are not multiple, different-length paths to the Express application such that the client can be less than the configured number of hops away, otherwise it may be possible for the client to provide any value. + +
Function +Custom trust implementation. + +```js +app.set('trust proxy', (ip) => { + if (ip === '127.0.0.1' || ip === '123.123.123.123') + return true; // trusted IPs + else return false; +}); +``` + +
+ +Enabling `trust proxy` will have the following impact: + +
    +
  • + The value of [req.hostname](/en/api#req.hostname) is derived from the value set in the + `X-Forwarded-Host` header, which can be set by the client or by the proxy. +
    • +
  • + `X-Forwarded-Proto` can be set by the reverse proxy to tell the app whether it is `https` or + `http` or even an invalid name. This value is reflected by [req.protocol](/en/api#req.protocol). +
    • +
  • + The [req.ip](/en/api#req.ip) and [req.ips](/en/api#req.ips) values are populated based on the + socket address and `X-Forwarded-For` header, starting at the first untrusted address. +
    • +
+ +The `trust proxy` setting is implemented using the [proxy-addr](https://www.npmjs.com/package/proxy-addr) package. For more information, see its documentation. diff --git a/src/content/docs/ko/5x/guide/debugging.mdx b/src/content/docs/ko/5x/guide/debugging.mdx new file mode 100644 index 0000000000..a7750f5427 --- /dev/null +++ b/src/content/docs/ko/5x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Debugging Express +description: Learn how to enable and use debugging logs in Express.js applications by setting the DEBUG environment variable for enhanced troubleshooting. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +To see all the internal logs used in Express, set the `DEBUG` environment variable to +`express:*` when launching your app. + +```bash +$ DEBUG=express:* node index.js +``` + +On Windows, use the corresponding command. + +```bash +> $env:DEBUG = "express:*"; node index.js +``` + +Running this command on the default app generated by the [express generator](/en/starter/generator) prints the following output: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +When a request is then made to the app, you will see the logs specified in the Express code: + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index.pug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +To see the logs only from the router implementation, set the value of `DEBUG` to `express:router`. Likewise, to see logs only from the application implementation, set the value of `DEBUG` to `express:application`, and so on. + +## Applications generated by `express` + +An application generated by the `express` command uses the `debug` module and its debug namespace is scoped to the name of the application. + +For example, if you generated the app with `$ express sample-app`, you can enable the debug statements with the following command: + +```bash +$ DEBUG=sample-app:* node ./bin/www +``` + +You can specify more than one debug namespace by assigning a comma-separated list of names: + +```bash +$ DEBUG=http,mail,express:* node index.js +``` + +## Advanced options + +When running through Node.js, you can set a few environment variables that will change the behavior of the debug logging: + +| Name | Purpose | +| ------------------- | ------------------------------------------------- | +| `DEBUG` | Enables/disables specific debugging namespaces. | +| `DEBUG_COLORS` | Whether or not to use colors in the debug output. | +| `DEBUG_DEPTH` | Object inspection depth. | +| `DEBUG_FD` | File descriptor to write debug output to. | +| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. | + + + +The environment variables beginning with `DEBUG_` end up being converted into an Options object +that gets used with `%o`/`%O` formatters. See the Node.js documentation for +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) for the complete +list. + + diff --git a/src/content/docs/ko/5x/guide/error-handling.mdx b/src/content/docs/ko/5x/guide/error-handling.mdx new file mode 100644 index 0000000000..78f1c86e92 --- /dev/null +++ b/src/content/docs/ko/5x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Error Handling +description: Understand how Express.js handles errors in synchronous and asynchronous code, and learn to implement custom error handling middleware for your applications. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Error Handling* refers to how Express catches and processes errors that +occur both synchronously and asynchronously. Express comes with a default error +handler so you don't need to write your own to get started. + +## Catching Errors + +It's important to ensure that Express catches all errors that occur while +running route handlers and middleware. + +Errors that occur in synchronous code inside route handlers and middleware +require no extra work. If synchronous code throws an error, then Express will +catch and process it. For example: + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Express will catch this on its own. +}); +``` + +For errors returned from asynchronous functions invoked by route handlers +and middleware, you must pass them to the `next()` function, where Express will +catch and process them. For example: + +```js +app.get('/', (req, res, next) => { + fs.readFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Pass errors to Express. + } else { + res.send(data); + } + }); +}); +``` + +Starting with Express 5, route handlers and middleware that return a Promise +will call `next(value)` automatically when they reject or throw an error. +For example: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = await getUserById(req.params.id); + res.send(user); +}); +``` + +If `getUserById` throws an error or rejects, `next` will be called with either +the thrown error or the rejected value. If no rejected value is provided, `next` +will be called with a default Error object provided by the Express router. + +If you pass anything to the `next()` function (except the string `'route'`), +Express regards the current request as being an error and will skip any +remaining non-error handling routing and middleware functions. + +If the callback in a sequence provides no data, only errors, you can simplify +this code as follows: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +In the above example, `next` is provided as the callback for `fs.writeFile`, +which is called with or without errors. If there is no error, the second +handler is executed, otherwise Express catches and processes the error. + +You must catch errors that occur in asynchronous code invoked by route handlers or +middleware and pass them to Express for processing. For example: + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + next(err); + } + }, 100); +}); +``` + +The above example uses a `try...catch` block to catch errors in the +asynchronous code and pass them to Express. If the `try...catch` +block were omitted, Express would not catch the error since it is not part of the synchronous +handler code. + +Use promises to avoid the overhead of the `try...catch` block or when using functions +that return promises. For example: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + .then(() => { + throw new Error('BROKEN'); + }) + .catch(next); // Errors will be passed to Express. +}); +``` + +Since promises automatically catch both synchronous errors and rejected promises, +you can simply provide `next` as the final catch handler and Express will catch errors, +because the catch handler is given the error as the first argument. + +You could also use a chain of handlers to rely on synchronous error +catching, by reducing the asynchronous code to something trivial. For example: + +```js +app.get('/', [ + function (req, res, next) { + fs.readFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals.data = data; + next(err); + }); + }, + function (req, res) { + res.locals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +The above example has a couple of trivial statements from the `readFile` +call. If `readFile` causes an error, then it passes the error to Express, otherwise you +quickly return to the world of synchronous error handling in the next handler +in the chain. Then, the example above tries to process the data. If this fails, then the +synchronous error handler will catch it. If you had done this processing inside +the `readFile` callback, then the application might exit and the Express error +handlers would not run. + +Whichever method you use, if you want Express error handlers to be called in and the +application to survive, you must ensure that Express receives the error. + +## The default error handler + +Express comes with a built-in error handler that takes care of any errors that might be encountered in the app. This default error-handling middleware function is added at the end of the middleware function stack. + +If you pass an error to `next()` and you do not handle it in a custom error +handler, it will be handled by the built-in error handler; the error will be +written to the client with the stack trace. The stack trace is not included +in the production environment. + + + +Set the environment variable `NODE_ENV` to `production`, to run the app in production mode. + + + +When an error is written, the following information is added to the +response: + +* The `res.statusCode` is set from `err.status` (or `err.statusCode`). If + this value is outside the 4xx or 5xx range, it will be set to 500. +* The `res.statusMessage` is set according to the status code. +* The body will be the HTML of the status code message when in production + environment, otherwise will be `err.stack`. +* Any headers specified in an `err.headers` object. + +If you call `next()` with an error after you have started writing the +response (for example, if you encounter an error while streaming the +response to the client), the Express default error handler closes the +connection and fails the request. + +So when you add a custom error handler, you must delegate to +the default Express error handler, when the headers +have already been sent to the client: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Note that the default error handler can get triggered if you call `next()` with an error +in your code more than once, even if custom error handling middleware is in place. + +Other error handling middleware can be found at [Express middleware](/en/resources/middleware). + +## Writing error handlers + +Define error-handling middleware functions in the same way as other middleware functions, +except error-handling functions have four arguments instead of three: +`(err, req, res, next)`. For example: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +You define error-handling middleware last, after other `app.use()` and routes calls; for example: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser.urlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app.use(methodOverride()); +app.use((err, req, res, next) => { + // logic +}); +``` + +Responses from within a middleware function can be in any format, such as an HTML error page, a simple message, or a JSON string. + +For organizational (and higher-level framework) purposes, you can define +several error-handling middleware functions, much as you would with +regular middleware functions. For example, to define an error-handler +for requests made by using `XHR` and those without: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser.urlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +In this example, the generic `logErrors` might write request and +error information to `stderr`, for example: + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +Also in this example, `clientErrorHandler` is defined as follows; in this case, the error is explicitly passed along to the next one. + +Notice that when *not* calling "next" in an error-handling function, you are responsible for writing (and ending) the response. Otherwise, those requests will "hang" and will not be eligible for garbage collection. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500).send({ error: 'Something failed!' }); + } else { + next(err); + } +} +``` + +Implement the "catch-all" `errorHandler` function as follows (for example): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +If you have a route handler with multiple callback functions, you can use the `route` parameter to skip to the next route handler. For example: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user.hasPaid) { + // continue handling this request + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent.find((err, doc) => { + if (err) return next(err); + res.json(doc); + }); + } +); +``` + +In this example, the `getPaidContent` handler will be skipped but any remaining handlers in `app` for `/a_route_behind_paywall` would continue to be executed. + + + +Calls to `next()` and `next(err)` indicate that the current handler is complete and in what state. +`next(err)` will skip all remaining handlers in the chain except for those that are set up to +handle errors as described above. + + diff --git a/src/content/docs/ko/5x/guide/overriding-express-api.md b/src/content/docs/ko/5x/guide/overriding-express-api.md new file mode 100644 index 0000000000..f5281a58f5 --- /dev/null +++ b/src/content/docs/ko/5x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Overriding the Express API +description: Discover how to customize and extend the Express.js API by overriding methods and properties on the request and response objects using prototypes. +--- + +The Express API consists of various methods and properties on the request and response objects. These are inherited by prototype. There are two extension points for the Express API: + +1. The global prototypes at `express.request` and `express.response`. +2. App-specific prototypes at `app.request` and `app.response`. + +Altering the global prototypes will affect all loaded Express apps in the same process. If desired, alterations can be made app-specific by only altering the app-specific prototypes after creating a new app. + +## Methods + +You can override the signature and behavior of existing methods with your own, by assigning a custom function. + +Following is an example of overriding the behavior of [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +The above implementation completely changes the original signature of `res.sendStatus`. It now accepts a status code, encoding type, and the message to be sent to the client. + +The overridden method may now be used this way: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## Properties + +Properties in the Express API are either: + +1. Assigned properties (ex: `req.baseUrl`, `req.originalUrl`) +2. Defined as getters (ex: `req.secure`, `req.ip`) + +Since properties under category 1 are dynamically assigned on the `request` and `response` objects in the context of the current request-response cycle, their behavior cannot be overridden. + +Properties under category 2 can be overwritten using the Express API extensions API. + +The following code rewrites how the value of `req.ip` is to be derived. Now, it simply returns the value of the `Client-IP` request header. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Prototype + +In order to provide the Express API, the request/response objects passed to Express (via `app(req, res)`, for example) need to inherit from the same prototype chain. By default, this is `http.IncomingRequest.prototype` for the request and `http.ServerResponse.prototype` for the response. + +Unless necessary, it is recommended that this be done only at the application level, rather than globally. Also, take care that the prototype that is being used matches the functionality as closely as possible to the default prototypes. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/ko/5x/guide/routing.mdx b/src/content/docs/ko/5x/guide/routing.mdx new file mode 100644 index 0000000000..78ab64f6e8 --- /dev/null +++ b/src/content/docs/ko/5x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Routing +description: Learn how to define and use routes in Express.js applications, including route methods, route paths, parameters, and using Router for modular routing. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* refers to how an application's endpoints (URIs) respond to client requests. +For an introduction to routing, see [Basic routing](/en/starter/basic-routing). + +You define routing using methods of the Express `app` object that correspond to HTTP methods; +for example, `app.get()` to handle GET requests and `app.post` to handle POST requests. For a full list, +see [app.METHOD](/en/5x/api#app.METHOD). You can also use [app.all()](/en/5x/api#app.all) to handle all HTTP methods and [app.use()](/en/5x/api#app.use) to +specify middleware as the callback function (See [Using middleware](/en/guide/using-middleware) for details). + +These routing methods specify a callback function (sometimes called "handler functions") called when the application receives a request to the specified route (endpoint) and HTTP method. In other words, the application "listens" for requests that match the specified route(s) and method(s), and when it detects a match, it calls the specified callback function. + +In fact, the routing methods can have more than one callback function as arguments. +With multiple callback functions, it is important to provide `next` as an argument to the callback function and then call `next()` within the body of the function to hand off control +to the next callback. + +The following code is an example of a very basic route. + +```js +const express = require('express'); +const app = express(); + +// respond with "hello world" when a GET request is made to the homepage +app.get('/', (req, res) => { + res.send('hello world'); +}); +``` + +## Route methods + +A route method is derived from one of the HTTP methods, and is attached to an instance of the `express` class. + +The following code is an example of routes that are defined for the `GET` and the `POST` methods to the root of the app. + +```js +// GET method route +app.get('/', (req, res) => { + res.send('GET request to the homepage'); +}); + +// POST method route +app.post('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Express supports methods that correspond to all HTTP request methods: `get`, `post`, and so on. +For a full list, see [app.METHOD](/en/5x/api#app.METHOD). + +There is a special routing method, `app.all()`, used to load middleware functions at a path for *all* HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Accessing the secret section ...'); + next(); // pass control to the next handler +}); +``` + +## Route paths + +Route paths, in combination with a request method, define the endpoints at which requests can be made. Route paths can be strings, string patterns, or regular expressions. + + + +In express 5, the characters `?`, `+`, `*`, `[]`, and `()` are handled differently than in version +4, please review the [migration guide](/en/guide/migrating-5#path-syntax) for more information. + + + + + +In express 4, regular expression characters such as `$` need to be escaped with a `\`. + + + + + +Express uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) for matching the route +paths; see the path-to-regexp documentation for all the possibilities in defining route paths. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) is a handy tool for +testing basic Express routes, although it does not support pattern matching. + + + +Query strings are not part of the route path. + +### Route paths based on strings + +This route path will match requests to the root route, `/`. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +This route path will match requests to `/about`. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +This route path will match requests to `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Route paths based on string patterns + + + +The string patterns in Express 5 no longer work. Please refer to the migration +guide for more information. + + + +This route path will match `acd` and `abcd`. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +This route path will match `abcd`, `abbcd`, `abbbcd`, and so on. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +This route path will match `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd`, and so on. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +This route path will match `/abe` and `/abcde`. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Route paths based on regular expressions + +This route path will match anything with an "a" in it. + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +This route path will match `butterfly` and `dragonfly`, but not `butterflyman`, `dragonflyman`, and so on. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Route parameters + +Route parameters are named URL segments that are used to capture the values specified at their position in the URL. The captured values are populated in the `req.params` object, with the name of the route parameter specified in the path as their respective keys. + +``` +Route path: /users/:userId/books/:bookId +Request URL: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +To define routes with route parameters, simply specify the route parameters in the path of the route as shown below. + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +The name of route parameters must be made up of "word characters" ([A-Za-z0-9_]). + + + +Since the hyphen (`-`) and the dot (`.`) are interpreted literally, they can be used along with route parameters for useful purposes. + +``` +Route path: /flights/:from-:to +Request URL: http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Route path: /plantae/:genus.:species +Request URL: http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +In express 5, Regexp characters are not supported in route paths, for more information please +refer to the [migration guide](/en/guide/migrating-5#path-syntax). + + + +To have more control over the exact string that can be matched by a route parameter, you can append a regular expression in parentheses (`()`): + +``` +Route path: /user/:userId(\d+) +Request URL: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Because the regular expression is usually part of a literal string, be sure to escape any `\` +characters with an additional backslash, for example `\d+`. + + + + +In Express 4.x, the `*` character in regular expressions is not interpreted in the usual way. As a workaround, use `{0,}` instead of `*`. This will likely be fixed in Express 5. + + +## Route handlers + +You can provide multiple callback functions that behave like [middleware](/en/guide/using-middleware) to handle a request. The only exception is that these callbacks might invoke `next('route')` to bypass the remaining route callbacks. You can use this mechanism to impose pre-conditions on a route, then pass control to subsequent routes if there's no reason to proceed with the current route. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params.id === '0') { + return next('route'); + } + res.send(`User ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Special handler for user ID 0'); +}); +``` + +In this example: + +* `GET /user/5` → handled by first route → sends "User 5" +* `GET /user/0` → first route calls `next('route')`, skipping to the next matching `/user/:id` route + +Route handlers can be in the form of a function, an array of functions, or combinations of both, as shown in the following examples. + +A single callback function can handle a route. For example: + +```js +app.get('/example/a', (req, res) => { + res.send('Hello from A!'); +}); +``` + +More than one callback function can handle a route (make sure you specify the `next` object). For example: + +```js +app.get( + '/example/b', + (req, res, next) => { + console.log('the response will be sent by the next function ...'); + next(); + }, + (req, res) => { + res.send('Hello from B!'); + } +); +``` + +An array of callback functions can handle a route. For example: + +```js +const cb0 = function (req, res, next) { + console.log('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console.log('CB1'); + next(); +}; + +const cb2 = function (req, res) { + res.send('Hello from C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +A combination of independent functions and arrays of functions can handle a route. For example: + +```js +const cb0 = function (req, res, next) { + console.log('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console.log('CB1'); + next(); +}; + +app.get( + '/example/d', + [cb0, cb1], + (req, res, next) => { + console.log('the response will be sent by the next function ...'); + next(); + }, + (req, res) => { + res.send('Hello from D!'); + } +); +``` + +## Response methods + +The methods on the response object (`res`) in the following table can send a response to the client, and terminate the request-response cycle. If none of these methods are called from a route handler, the client request will be left hanging. + +| Method | Description | +| --------------------------------------------- | ------------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | Prompt a file to be downloaded. | +| [res.end()](/en/5x/api#res.end) | End the response process. | +| [res.json()](/en/5x/api#res.json) | Send a JSON response. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Send a JSON response with JSONP support. | +| [res.redirect()](/en/5x/api#res.redirect) | Redirect a request. | +| [res.render()](/en/5x/api#res.render) | Render a view template. | +| [res.send()](/en/5x/api#res.send) | Send a response of various types. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Send a file as an octet stream. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Set the response status code and send its string representation as the response body. | + +## app.route() + +You can create chainable route handlers for a route path by using `app.route()`. +Because the path is specified at a single location, creating modular routes is helpful, as is reducing redundancy and typos. For more information about routes, see: [Router() documentation](/en/5x/api#router). + +Here is an example of chained route handlers that are defined by using `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res.send('Get a random book'); + }) + .post((req, res) => { + res.send('Add a book'); + }) + .put((req, res) => { + res.send('Update the book'); + }); +``` + +## express.Router + +Use the `express.Router` class to create modular, mountable route handlers. A `Router` instance is a complete middleware and routing system; for this reason, it is often referred to as a "mini-app". + +The following example creates a router as a module, loads a middleware function in it, defines some routes, and mounts the router module on a path in the main app. + +Create a router file named `birds.js` in the app directory, with the following content: + +```js +const express = require('express'); +const router = express.Router(); + +// middleware that is specific to this router +const timeLog = (req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}; +router.use(timeLog); + +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Then, load the router module in the app: + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +The app will now be able to handle requests to `/birds` and `/birds/about`, as well as call the `timeLog` middleware function that is specific to the route. + +But if the parent route `/birds` has path parameters, it will not be accessible by default from the sub-routes. To make it accessible, you will need to pass the `mergeParams` option to the Router constructor [reference](/en/5x/api#app.use). + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/ko/5x/guide/using-middleware.mdx b/src/content/docs/ko/5x/guide/using-middleware.mdx new file mode 100644 index 0000000000..026542a234 --- /dev/null +++ b/src/content/docs/ko/5x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Using middleware +description: Learn how to use middleware in Express.js applications, including application-level and router-level middleware, error handling, and integrating third-party middleware. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express is a routing and middleware web framework that has minimal functionality of its own: An Express application is essentially a series of middleware function calls. + +*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. + +Middleware functions can perform the following tasks: + +* Execute any code. +* Make changes to the request and the response objects. +* End the request-response cycle. +* Call the next middleware function in the stack. + +If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. + +An Express application can use the following types of middleware: + +* [Application-level middleware](#middleware.application) +* [Router-level middleware](#middleware.router) +* [Error-handling middleware](#middleware.error-handling) +* [Built-in middleware](#middleware.built-in) +* [Third-party middleware](#middleware.third-party) + +You can load application-level and router-level middleware with an optional mount path. +You can also load a series of middleware functions together, which creates a sub-stack of the middleware system at a mount point. + +## Application-level middleware + +Bind application-level middleware to an instance of the [app object](/en/5x/api#app) by using the `app.use()` and `app.METHOD()` functions, where `METHOD` is the HTTP method of the request that the middleware function handles (such as GET, PUT, or POST) in lowercase. + +This example shows a middleware function with no mount path. The function is executed every time the app receives a request. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +This example shows a middleware function mounted on the `/user/:id` path. The function is executed for any type of +HTTP request on the `/user/:id` path. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +This example shows a route and its handler function (middleware system). The function handles GET requests to the `/user/:id` path. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +Here is an example of loading a series of middleware functions at a mount point, with a mount path. +It illustrates a middleware sub-stack that prints request info for any type of HTTP request to the `/user/:id` path. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); +``` + +Route handlers enable you to define multiple routes for a path. The example below defines two routes for GET requests to the `/user/:id` path. The second route will not cause any problems, but it will never get called because the first route ends the request-response cycle. + +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req.params.id); + next(); + }, + (req, res, next) => { + res.send('User Info'); + } +); + +// handler for the /user/:id path, which prints the user ID +app.get('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +To skip the rest of the middleware functions from a router middleware stack, call `next('route')` to pass control to the next route. + + + +`next('route')` will work only in middleware functions that were loaded by using the +`app.METHOD()` or `router.METHOD()` functions. + + + +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. + +```js +app.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next route + if (req.params.id === '0') next('route'); + // otherwise pass the control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // send a regular response + res.send('regular'); + } +); + +// handler for the /user/:id path, which sends a special response +app.get('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +Middleware can also be declared in an array for reusability. + +This example shows an array with a middleware sub-stack that handles GET requests to the `/user/:id` path + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req.originalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Request Type:', req.method); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app.get('/user/:id', logStuff, (req, res, next) => { + res.send('User Info'); +}); +``` + +## Router-level middleware + +Router-level middleware works in the same way as application-level middleware, except it is bound to an instance of `express.Router()`. + +```js +const router = express.Router(); +``` + +Load router-level middleware by using the `router.use()` and `router.METHOD()` functions. + +The following example code replicates the middleware system that is shown above for application-level middleware, by using router-level middleware: + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// a middleware function with no mount path. This code is executed for every request to the router +router.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); + +// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path +router.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); + +// a middleware sub-stack that handles GET requests to the /user/:id path +router.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next router + if (req.params.id === '0') next('route'); + // otherwise pass control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // render a regular page + res.render('regular'); + } +); + +// handler for the /user/:id path, which renders a special page +router.get('/user/:id', (req, res, next) => { + console.log(req.params.id); + res.render('special'); +}); + +// mount the router on the app +app.use('/', router); +``` + +To skip the rest of the router's middleware functions, call `next('router')` +to pass control back out of the router instance. + +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// predicate the router with a check and bail out when needed +router.use((req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router.get('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// use the router and 401 anything falling through +app.use('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## Error-handling middleware + + + +Error-handling middleware always takes *four* arguments. You must provide four arguments to +identify it as an error-handling middleware function. Even if you don't need to use the `next` +object, you must specify it to maintain the signature. Otherwise, the `next` object will be +interpreted as regular middleware and will fail to handle errors. + + + +Define error-handling middleware functions in the same way as other middleware functions, except with four arguments instead of three, specifically with the signature `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +For details about error-handling middleware, see: [Error handling](/en/guide/error-handling). + +## Built-in middleware + +Starting with version 4.x, Express no longer depends on [Connect](https://github.com/senchalabs/connect). The middleware +functions that were previously included with Express are now in separate modules; see [the list of middleware functions](https://github.com/senchalabs/connect#middleware). + +Express has the following built-in middleware functions: + +* [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. +* [express.json](/en/5x/api#express.json) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** + +## Third-party middleware + +Use third-party middleware to add functionality to Express apps. + +Install the Node.js module for the required functionality, then load it in your app at the application level or at the router level. + +The following example illustrates installing and loading the cookie-parsing middleware function `cookie-parser`. + +```bash +$ npm install cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// load the cookie-parsing middleware +app.use(cookieParser()); +``` + +For a partial list of third-party middleware functions that are commonly used with Express, see: [Third-party middleware](../resources/middleware). diff --git a/src/content/docs/ko/5x/guide/using-template-engines.mdx b/src/content/docs/ko/5x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..7095bc6dd5 --- /dev/null +++ b/src/content/docs/ko/5x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Using template engines with Express +description: Discover how to integrate and use template engines like Pug, Handlebars, and EJS with Express.js to render dynamic HTML pages efficiently. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +A *template engine* enables you to use static template files in your application. At runtime, the template engine replaces +variables in a template file with actual values, and transforms the template into an HTML file sent to the client. +This approach makes it easier to design an HTML page. + +The [Express application generator](/en/starter/generator) uses [Pug](https://pugjs.org/api/getting-started.html) as its default, but it also supports [Handlebars](https://www.npmjs.com/package/handlebars), and [EJS](https://www.npmjs.com/package/ejs), among others. + +To render template files, set the following [application setting properties](/en/4x/api#app.set), in the default `app.js` created by the generator: + +* `views`, the directory where the template files are located. Eg: `app.set('views', './views')`. + This defaults to the `views` directory in the application root directory. +* `view engine`, the template engine to use. For example, to use the Pug template engine: `app.set('view engine', 'pug')`. + +Then install the corresponding template engine npm package; for example to install Pug: + +```bash +$ npm install pug --save +``` + + +Express-compliant template engines such as Pug export a function named `__express(filePath, options, callback)`, +which `res.render()` calls to render the template code. + +Some template engines do not follow this convention. The [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +library follows this convention by mapping all of the popular Node.js template engines, and therefore works seamlessly within Express. + + + +After the view engine is set, you don't have to specify the engine or load the template engine module in your app; +Express loads the module internally, for example: + +```js +app.set('view engine', 'pug'); +``` + +Then, create a Pug template file named `index.pug` in the `views` directory, with the following content: + +```pug +html + head + title= title + body + h1= message +``` + +Create a route to render the `index.pug` file. If the `view engine` property is not set, +you must specify the extension of the `view` file. Otherwise, you can omit it. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +When you make a request to the home page, the `index.pug` file will be rendered as HTML. + +The view engine cache does not cache the contents of the template's output, only the underlying template itself. The view is still re-rendered with every request even when the cache is on. diff --git a/src/content/docs/ko/5x/guide/writing-middleware.mdx b/src/content/docs/ko/5x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..a22cd12f84 --- /dev/null +++ b/src/content/docs/ko/5x/guide/writing-middleware.mdx @@ -0,0 +1,209 @@ +--- +title: Writing middleware for use in Express apps +description: Learn how to write custom middleware functions for Express.js applications, including examples and best practices for enhancing request and response handling. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. + +Middleware functions can perform the following tasks: + +* Execute any code. +* Make changes to the request and the response objects. +* End the request-response cycle. +* Call the next middleware in the stack. + +If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. + +The following figure shows the elements of a middleware function call: + +![Elements of a middleware function call](/images/express-mw.png) + +Starting with Express 5, middleware functions that return a Promise will call `next(value)` when they reject or throw an error. `next` will be called with either the rejected value or the thrown Error. + +## Example + +Here is an example of a simple "Hello World" Express application. +The remainder of this article will define and add three middleware functions to the application: +one called `myLogger` that prints a simple log message, one called `requestTime` that +displays the timestamp of the HTTP request, and one called `validateCookies` that validates incoming cookies. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +### Middleware function myLogger + +Here is a simple example of a middleware function called "myLogger". This function just prints +"LOGGED" when a request to the app passes through it. The middleware function is assigned to a +variable named `myLogger`. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +Notice the call above to `next()`. Calling this function invokes the next middleware function in +the app. The `next()` function is not a part of the Node.js or Express API, but is the third +argument that is passed to the middleware function. The `next()` function could be named anything, +but by convention it is always named "next". To avoid confusion, always use this convention. + + + +To load the middleware function, call `app.use()`, specifying the middleware function. +For example, the following code loads the `myLogger` middleware function before the route to the root path (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +Every time the app receives a request, it prints the message "LOGGED" to the terminal. + +The order of middleware loading is important: middleware functions that are loaded first are also executed first. + +If `myLogger` is loaded after the route to the root path, the request never reaches it and the app doesn't print "LOGGED", because the route handler of the root path terminates the request-response cycle. + +The middleware function `myLogger` simply prints a message, then passes on the request to the next middleware function in the stack by calling the `next()` function. + +### Middleware function requestTime + +Next, we'll create a middleware function called "requestTime" and add a property called `requestTime` +to the request object. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +The app now uses the `requestTime` middleware function. Also, the callback function of the root path route uses the property that the middleware function adds to `req` (the request object). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app.get('/', (req, res) => { + let responseText = 'Hello World!
'; + responseText += `Requested at: ${req.requestTime}`; + res.send(responseText); +}); + +app.listen(3000); +``` + +When you make a request to the root of the app, the app now displays the timestamp of your request in the browser. + +### Middleware function validateCookies + +Finally, we'll create a middleware function that validates incoming cookies and sends a 400 response if cookies are invalid. + +Here's an example function that validates cookies with an external async service. + +```js +async function cookieValidator(cookies) { + try { + await externallyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Invalid cookies'); + } +} +``` + +Here, we use the [`cookie-parser`](/en/resources/middleware/cookie-parser) middleware to parse incoming cookies off the `req` object and pass them to our `cookieValidator` function. The `validateCookies` middleware returns a Promise that upon rejection will automatically trigger our error handler. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('./cookieValidator'); + +const app = express(); + +async function validateCookies(req, res, next) { + await cookieValidator(req.cookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// error handler +app.use((err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Note how `next()` is called after `await cookieValidator(req.cookies)`. This ensures that if +`cookieValidator` resolves, the next middleware in the stack will get called. If you pass anything +to the `next()` function (except the string `'route'` or `'router'`), Express regards the current +request as being an error and will skip any remaining non-error handling routing and middleware +functions. + + + +Because you have access to the request object, the response object, the next middleware function in the stack, and the whole Node.js API, the possibilities with middleware functions are endless. + +For more information about Express middleware, see: [Using Express middleware](/en/guide/using-middleware). + +## Configurable middleware + +If you need your middleware to be configurable, export a function which accepts an options object or other parameters, which, then returns the middleware implementation based on the input parameters. + +File: `my-middleware.js` + +```js +module.exports = function (options) { + return function (req, res, next) { + // Implement the middleware function based on the options object + next(); + }; +}; +``` + +The middleware can now be used as shown below. + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Refer to [cookie-session](https://github.com/expressjs/cookie-session) and [compression](https://github.com/expressjs/compression) for examples of configurable middleware. diff --git a/src/content/docs/ko/5x/starter/basic-routing.mdx b/src/content/docs/ko/5x/starter/basic-routing.mdx new file mode 100644 index 0000000000..35d674808b --- /dev/null +++ b/src/content/docs/ko/5x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Basic routing +description: Learn the fundamentals of routing in Express.js applications, including how to define routes, handle HTTP methods, and create route handlers for your web server. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). + +Each route can have one or more handler functions, which are executed when the route is matched. + +Route definition takes the following structure: + +```js +app.METHOD(PATH, HANDLER); +``` + +Where: + +* `app` is an instance of `express`. +* `METHOD` is an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in lowercase. +* `PATH` is a path on the server. +* `HANDLER` is the function executed when the route is matched. + + + +This tutorial assumes that an instance of `express` named `app` is created and the server is +running. If you are not familiar with creating an app and starting it, see the Hello world +example. + + + +The following examples illustrate defining simple routes. + +Respond with `Hello World!` on the homepage: + +```js +app.get('/', (req, res) => { + res.send('Hello World!'); +}); +``` + +Respond to a POST request on the root route (`/`), the application's home page: + +```js +app.post('/', (req, res) => { + res.send('Got a POST request'); +}); +``` + +Respond to a PUT request to the `/user` route: + +```js +app.put('/user', (req, res) => { + res.send('Got a PUT request at /user'); +}); +``` + +Respond to a DELETE request to the `/user` route: + +```js +app.delete('/user', (req, res) => { + res.send('Got a DELETE request at /user'); +}); +``` + +For more details about routing, see the [routing guide](/en/guide/routing). diff --git a/src/content/docs/ko/5x/starter/examples.mdx b/src/content/docs/ko/5x/starter/examples.mdx new file mode 100644 index 0000000000..eccdf984c2 --- /dev/null +++ b/src/content/docs/ko/5x/starter/examples.mdx @@ -0,0 +1,49 @@ +--- +title: Express examples +description: Explore a collection of Express.js application examples covering various use cases, integrations, and advanced configurations to help you learn and build your projects. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +This page contains list of examples using Express. + +* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Authentication with login and password +* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - HTTP content negotiation +* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Working with cookie-based sessions +* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Working with cookies +* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transferring files to client +* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Working with Embedded JavaScript templating (ejs) +* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Creating error pages +* [error](https://github.com/expressjs/express/tree/master/examples/error) - Working with error middleware +* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Simple request handler +* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown as template engine +* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Working with multiple Express routers +* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - MVC-style controllers +* [online](https://github.com/expressjs/express/tree/master/examples/online) - Tracking online user activity with `online` and `redis` packages +* [params](https://github.com/expressjs/express/tree/master/examples/params) - Working with route parameters +* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Multiple HTTP operations on the same resource +* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organizing routes using a map +* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Working with route middleware +* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizing routes per each resource +* [search](https://github.com/expressjs/express/tree/master/examples/search) - Search API +* [session](https://github.com/expressjs/express/tree/master/examples/session) - User sessions +* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Serving static files +* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Working with virtual hosts +* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Rendering views dynamically +* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Saving data in request object between middleware calls +* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Simple API service + +## Additional examples + +These are some additional examples with more extensive integrations. + + + +This information refers to third-party sites, products, or modules that are not maintained by the +Expressjs team. Listing here does not constitute an endorsement or recommendation from the +Expressjs project team. + + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app with Express and Next.js using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM diff --git a/src/content/docs/ko/5x/starter/faq.md b/src/content/docs/ko/5x/starter/faq.md new file mode 100644 index 0000000000..1adcb7be0e --- /dev/null +++ b/src/content/docs/ko/5x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: FAQ +description: Find answers to frequently asked questions about Express.js, including topics on application structure, models, authentication, template engines, error handling, and more. +--- + +## How should I structure my application? + +There is no definitive answer to this question. The answer depends +on the scale of your application and the team that is involved. To be as +flexible as possible, Express makes no assumptions in terms of structure. + +Routes and other application-specific logic can live in as many files +as you wish, in any directory structure you prefer. View the following +examples for inspiration: + +- [Route listings](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Route map](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Also, there are third-party extensions for Express, which simplify some of these patterns: + +- [Resourceful routing](https://github.com/expressjs/express-resource) + +## How do I define models? + +Express has no notion of a database. This concept is +left up to third-party Node modules, allowing you to +interface with nearly any database. + +See [LoopBack](http://loopback.io) for an Express-based framework that is centered around models. + +## How can I authenticate users? + +Authentication is another opinionated area that Express does not +venture into. You may use any authentication scheme you wish. +For a simple username / password scheme, see [this example](https://github.com/expressjs/express/tree/master/examples/auth). + +## Which template engines does Express support? + +Express supports any template engine that conforms with the `(path, locals, callback)` signature. +To normalize template engine interfaces and caching, see the +[consolidate.js](https://github.com/visionmedia/consolidate.js) +project for support. Unlisted template engines might still support the Express signature. + +For more information, see [Using template engines with Express](/en/guide/using-template-engines). + +## How do I handle 404 responses? + +In Express, 404 responses are not the result of an error, so +the error-handler middleware will not capture them. This behavior is +because a 404 response simply indicates the absence of additional work to do; +in other words, Express has executed all middleware functions and routes, +and found that none of them responded. All you need to +do is add a middleware function at the very bottom of the stack (below all other functions) +to handle a 404 response: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Add routes dynamically at runtime on an instance of `express.Router()` +so the routes are not superseded by a middleware function. + +## How do I setup an error handler? + +You define error-handling middleware in the same way as other middleware, +except with four arguments instead of three; specifically with the signature `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +For more information, see [Error handling](/en/guide/error-handling). + +## How do I render plain HTML? + +You don't! There's no need to "render" HTML with the `res.render()` function. +If you have a specific file, use the `res.sendFile()` function. +If you are serving many assets from a directory, use the `express.static()` +middleware function. + +## What version of Node.js does Express require? + +- [Express 4.x](/en/4x/api) requires Node.js 0.10 or higher. +- [Express 5.x](/en/5x/api) requires Node.js 18 or higher. diff --git a/src/content/docs/ko/5x/starter/generator.mdx b/src/content/docs/ko/5x/starter/generator.mdx new file mode 100644 index 0000000000..859bec927e --- /dev/null +++ b/src/content/docs/ko/5x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Express application generator +description: Learn how to use the Express application generator tool to quickly create a skeleton for your Express.js applications, streamlining setup and configuration. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Use the application generator tool, `express-generator`, to quickly create an application skeleton. + +You can run the application generator with the `npx` command (available in Node.js 8.2.0). + +```bash +$ npx express-generator +``` + +For earlier Node versions, install the application generator as a global npm package and then launch it: + +```bash +$ npm install -g express-generator +$ express +``` + +Display the command options with the `-h` option: + +```bash +$ express -h + + Usage: express [options] [dir] + + Options: + + -h, --help output usage information + --version output the version number + -e, --ejs add ejs engine support + --hbs add handlebars engine support + --pug add pug engine support + -H, --hogan add hogan.js engine support + --no-view generate without view engine + -v, --view add view support (ejs|hbs|hjs|jade|pug|twig|vash) (defaults to jade) + -c, --css add stylesheet support (less|stylus|compass|sass) (defaults to plain css) + --git add .gitignore + -f, --force force on non-empty directory +``` + +For example, the following creates an Express app named *myapp*. The app will be created in a folder named *myapp* in the current working directory and the view engine will be set to Pug: + +```bash +$ express --view=pug myapp + + create : myapp + create : myapp/package.json + create : myapp/app.js + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index.js + create : myapp/routes/users.js + create : myapp/public/stylesheets + create : myapp/public/stylesheets/style.css + create : myapp/views + create : myapp/views/index.pug + create : myapp/views/layout.pug + create : myapp/views/error.pug + create : myapp/bin + create : myapp/bin/www +``` + +Then install dependencies: + +```bash +$ cd myapp +$ npm install +``` + +On MacOS or Linux, run the app with this command: + +```bash +$ DEBUG=myapp:* npm start +``` + +On Windows Command Prompt, use this command: + +```bash +> set DEBUG=myapp:* & npm start +``` + +On Windows PowerShell, use this command: + +```bash +PS> $env:DEBUG='myapp:*'; npm start +``` + +Then, load `http://localhost:3000/` in your browser to access the app. + +The generated app has the following directory structure: + +```bash +. +├── app.js +├── bin +│ └── www +├── package.json +├── public +│ ├── images +│ ├── javascripts +│ └── stylesheets +│ └── style.css +├── routes +│ ├── index.js +│ └── users.js +└── views + ├── error.pug + ├── index.pug + └── layout.pug + +7 directories, 9 files +``` + + + +The app structure created by the generator is just one of many ways to structure Express apps. +Feel free to use this structure or modify it to best suit your needs. + + diff --git a/src/content/docs/ko/5x/starter/hello-world.mdx b/src/content/docs/ko/5x/starter/hello-world.mdx new file mode 100644 index 0000000000..d92beecd0a --- /dev/null +++ b/src/content/docs/ko/5x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Hello world example +description: Get started with Express.js by building a simple 'Hello World' application, demonstrating the basic setup and server creation for beginners. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Embedded below is essentially the simplest Express app you can create. It is a single file app +— *not* what you'd get if you use the [Express generator](/en/starter/generator), which +creates the scaffolding for a full app with numerous JavaScript files, Jade templates, and +sub-directories for various purposes. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(port, () => { + console.log(`Example app listening on port ${port}`); +}); +``` + +This app starts a server and listens on port 3000 for connections. The app responds with "Hello World!" for requests +to the root URL (`/`) or *route*. For every other path, it will respond with a **404 Not Found**. + +## Running Locally + +First create a directory named `myapp`, change to it and run `npm init`. Then, install `express` as a dependency, as per the [installation guide](/en/starter/installing). + +In the `myapp` directory, create a file named `app.js` and copy the code from the example above. + + + +The `req` (request) and `res` (response) are the exact same objects that Node provides, so you can +invoke `req.pipe()`, `req.on('data', callback)`, and anything else you would do without Express +involved. + + + +Run the app with the following command: + +```bash +$ node app.js +``` + +Then, load `http://localhost:3000/` in a browser to see the output. diff --git a/src/content/docs/ko/5x/starter/installing.mdx b/src/content/docs/ko/5x/starter/installing.mdx new file mode 100644 index 0000000000..f6dc8220d4 --- /dev/null +++ b/src/content/docs/ko/5x/starter/installing.mdx @@ -0,0 +1,41 @@ +--- +title: Installing +description: Learn how to install Express.js in your Node.js environment, including setting up your project directory and managing dependencies with npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Before you begin, make sure you have [Node.js](https://nodejs.org/) 18 or higher installed. Then, create a directory for your application and navigate into it. + +```bash +mkdir myapp +cd myapp +``` + +Use the `npm init` command to create a `package.json` file for your application. +For more information on how `package.json` works, see [Specifics of npm's package.json handling](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +This command prompts you for a number of things, such as the name and version of your application. +For now, you can simply hit RETURN to accept the defaults for most of them, with the following exception: + +``` +entry point: (index.js) +``` + +Enter `app.js`, or whatever you want the name of the main file to be. If you want it to be `index.js`, hit RETURN to accept the suggested default file name. + +Now, install Express in the `myapp` directory and save it in the dependencies list. For example: + +```bash +npm install express +``` + +To install Express temporarily and not add it to the dependencies list: + +```bash +npm install express --no-save +``` diff --git a/src/content/docs/ko/5x/starter/static-files.mdx b/src/content/docs/ko/5x/starter/static-files.mdx new file mode 100644 index 0000000000..98855e0d05 --- /dev/null +++ b/src/content/docs/ko/5x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Serving static files in Express +description: Understand how to serve static files like images, CSS, and JavaScript in Express.js applications using the built-in 'static' middleware. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +To serve static files such as images, CSS files, and JavaScript files, use the `express.static` built-in middleware function in Express. + +The function signature is: + +```js +express.static(root, [options]); +``` + +The `root` argument specifies the root directory from which to serve static assets. +For more information on the `options` argument, see [express.static](/en/5x/api#express.static). + +For example, use the following code to serve images, CSS files, and JavaScript files in a directory named `public`: + +```js +app.use(express.static('public')); +``` + +Now, you can load the files that are in the `public` directory: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express looks up the files relative to the static directory, so the name of the static directory +is not part of the URL. + + + +To use multiple static assets directories, call the `express.static` middleware function multiple times: + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express looks up the files in the order in which you set the static directories with the `express.static` middleware function. + + + +For best results, use a reverse +proxy cache to improve performance of +serving static assets. + + + +To create a virtual path prefix (where the path does not actually exist in the file system) for files that are served by the `express.static` function, [specify a mount path](/en/5x/api#app.use) for the static directory, as shown below: + +```js +app.use('/static', express.static('public')); +``` + +Now, you can load the files that are in the `public` directory from the `/static` path prefix. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +However, the path that you provide to the `express.static` function is relative to the directory from where you launch your `node` process. If you run the express app from another directory, it's safer to use the absolute path of the directory that you want to serve: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public'))); +``` + +For more details about the `serve-static` function and its options, see [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/pt-br/4x/advanced/developing-template-engines.md b/src/content/docs/pt-br/4x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..8b379a6f50 --- /dev/null +++ b/src/content/docs/pt-br/4x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Desenvolvendo modelos de motores para Express +description: Aprenda a desenvolver motores de modelos personalizados para Express.js usando app.engine(), com exemplos sobre como criar e integrar sua própria lógica de renderização de templates. +--- + +Use o método `app.engine(ext, callback)` para criar o seu próprio motor de templates. `ext` refere-se à extensão de arquivo, e `callback` é a função template engine que aceita os seguintes itens como parâmetros: a localização do arquivo, o objeto de opções e a função de retorno de chamada. + +O código a seguir é um exemplo de implementação de um mecanismo muito simples de template para renderizar arquivos `.ntl`. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +Seu aplicativo poderá renderizar arquivos `.ntl`. Crie um arquivo chamado `index.ntl` no diretório `views` com o seguinte conteúdo. + +```pug +#title# +#message# +``` + +Em seguida, crie a seguinte rota no seu app. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +Quando você fizer uma solicitação à página inicial, `index.ntl` será processado como HTML. diff --git a/src/content/docs/pt-br/4x/guide/behind-proxies.mdx b/src/content/docs/pt-br/4x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..1880b62ed0 --- /dev/null +++ b/src/content/docs/pt-br/4x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Expresso atrás dos proxies +description: Aprenda a configurar os aplicativos Express.js para funcionar corretamente atrás de proxies reversas, incluindo o uso do proxy confiável para manipular endereços IP do cliente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Ao executar um app Expresso atrás de um proxy reverso, alguns das APIs Express podem retornar valores diferentes do esperado. A fim de se ajustar para isto, a configuração do aplicativo `trust proxy` pode ser usada para expor informações fornecidas pelo proxy reverso na API Express. O problema mais comum é expressar APIs que expõem o endereço IP do cliente pode mostrar um endereço IP interno do proxy inverso. + + + +Ao configurar a configuração `proxy confiável`, é importante entender a configuração exata do proxy reverso +. Como esta configuração confiará nos valores fornecidos na solicitação, é importante que +a combinação da configuração no Express corresponda a como o proxy reverso funciona. + + + +A configuração do aplicativo 'proxy confiável' pode ser definida para um dos valores listados na tabela a seguir. + + + + + + + + + + + + + + + + + + + + + +
DigiteValor
Boolean +Se `true`, o endereço IP do cliente é entendido como a entrada mais à esquerda no cabeçalho `X-Forwarded-For`. + +Se `false`, o aplicativo é entendido como diretamente virado para o cliente e o endereço IP do cliente é derivado de `req.socket.remoteAddress`. Esta é a configuração padrão. + + +Ao definir como `true`, é importante garantir que o último proxy reverso confiável esteja removendo/substituindo todos os seguintes cabeçalhos HTTP: `X-Forwarded-for`, `X-Forwarded-Host` e `X-Forwarded-Proto`, caso contrário, pode ser possível que o cliente forneça qualquer valor. + +
endereços IP +Um endereço IP, subnet ou uma matriz de endereços IP e subnets para confiar como sendo um proxy reverso. A seguinte lista mostra os nomes das sub-redes pré-configuradas: + +* loopback - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +Você pode definir endereços IP das seguintes maneiras: + +```js +app.set('trust proxy', 'loopback'); // especifica um subnet +app.set('trust proxy', 'loopback, 123.123.123.123'); // especifica um subnet e um aplicativo de endereço +. et('proxy de confiança', 'loopback, linklocal, uniquelocal'); // especificar múltiplas subnets como CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // especificar várias subnets como um array +``` + +Quando especificado, os endereços IP ou as subredes são excluídos do processo de determinação de endereço, e o endereço IP não confiável mais próximo do servidor de aplicativos é definido como o endereço IP do cliente. Isto funciona verificando se 'req.socket.remoteAddress' é confiável. Em caso afirmativo, então cada endereço em `X-Forwarded-For` é verificado da direita para a esquerda até o primeiro endereço não confiável. + +
Número +Use o endereço que, no máximo, está fora do número de hops do aplicativo Express. `req.socket.remoteAddress` é o primeiro hop, e o resto é procurado no cabeçalho `X-Forwarded-for` da direita para a esquerda. Um valor de `0` significa que o primeiro endereço não confiável seria `req.socket.remoteAddress`, ou seja, não há um proxy reverso. + + +Ao usar esta configuração, é importante garantir que não haja vários, caminhos de comprimento diferente para o aplicativo Express, para que o cliente possa ser menor que o número configurado de saltos de distância, caso contrário, poderá ser possível que o cliente forneça qualquer valor. + +
Função +Execução de confiança personalizada. + +```js +app.set('proxy de confiança', (ip) => { + if (ip === '127.0.0.1' ├ip === '123.123.123. 23') + return true; // IPs + else return false; +}); +``` + +
+ +Habilitar `trust proxy` terá o seguinte impacto: + +
    +
  • + O valor de [req.hostname](/en/api#req.hostname) é derivado do valor definido no cabeçalho + `X-Forwarded-Host`, que pode ser configurado pelo cliente ou pelo proxy. +
    • +
  • + `X-Forwarded-Proto` pode ser configurado pelo proxy reverso para dizer ao aplicativo se ele é `https` ou + `http` ou até mesmo um nome inválido. Este valor é refletido por [req.protocol](/en/api#req.protocol). +
    • +
  • + Os valores [req.ip](/en/api#req.ip) e [req.ips](/en/api#req.ips) são preenchidos com base no cabeçalho + do socket e `X-Forwarded-For`, iniciando no primeiro endereço não confiável. +
    • +
+ +A configuração `trust proxy` é implementada usando o pacote [proxy-addr](https://www.npmjs.com/package/proxy-addr). Para obter mais informações, consulte a documentação. diff --git a/src/content/docs/pt-br/4x/guide/debugging.mdx b/src/content/docs/pt-br/4x/guide/debugging.mdx new file mode 100644 index 0000000000..66690a4946 --- /dev/null +++ b/src/content/docs/pt-br/4x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Expresso de depuração +description: Aprenda a habilitar e usar logs de depuração nos aplicativos Express.js definindo a variável de ambiente DEBUG para melhorar a solução de problemas. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Para ver todos os logs internos usados no Express, defina a variável de ambiente `DEBUG` para +`express:*` ao iniciar seu aplicativo. + +```bash +$ DEBUG=express:* node index.js +``` + +No Windows, use o comando correspondente. + +```bash +> $env:DEBUG = "express:*"; node index.js +``` + +Executar este comando no aplicativo padrão gerado pelo [gerador expresso](/en/starter/generator) imprime a seguinte saída: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +Quando um pedido for feito ao aplicativo, você verá os logs especificados no código Expresso: + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index.pug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +Para ver os logs apenas da implementação do roteador, defina o valor de `DEBUG` para `express:router`. Da mesma forma, para ver apenas os logs da implementação do aplicativo, defina o valor de `DEBUG` para `express:application`, e assim por diante. + +## Aplicações geradas por `express` + +Uma aplicação gerada pelo comando `express` usa o módulo `debug` e seu namespace de depuração é escopo para o nome da aplicação. + +Por exemplo, se você gerou o app com `$ express sample-app`, você pode ativar as instruções de depuração com o seguinte comando: + +```bash +$ DEBUG=sample-app:* node ./bin/www +``` + +Você pode especificar mais de um namespace de depuração atribuindo uma lista de nomes separada por vírgulas: + +```bash +$ DEBUG=http,mail,express:* node index.js +``` + +## Opções avançadas + +Ao executar através do Node.js, você pode definir algumas variáveis de ambiente que irão mudar o comportamento do log de depuração: + +| Nome: | Objetivo | +| ------------------- | -------------------------------------------------------- | +| `DEBUG` | Habilita/desabilita namespace específicos de depuração. | +| `DEBUG_COLORS` | Usar ou não cores na saída de depuração. | +| DEBUG_DEPTH\` | Profundidade da inspeção de objeto. | +| `DEBUG_FD` | Descritor de arquivo para escrever a saída de depuração. | +| `DEBUG_SHOW_HIDDEN` | Mostra propriedades ocultas em objetos inspecionados. | + + + +As variáveis de ambiente começando com `DEBUG_` acabam sendo convertidas em um objeto de Opções +que é usado com formatos `%o`/`%O`. Veja a documentação do Node.js sobre +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) para a lista +completa. + + diff --git a/src/content/docs/pt-br/4x/guide/error-handling.mdx b/src/content/docs/pt-br/4x/guide/error-handling.mdx new file mode 100644 index 0000000000..c0d1aa28c7 --- /dev/null +++ b/src/content/docs/pt-br/4x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Tratamento de erros +description: Entenda como o Express.js lida com erros em código síncrono e assíncrono e aprenda a implementar erro personalizado de manipulação de intermediários para seus aplicativos. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Tratamento de erros* refere-se a como as capturas Expressas e processa erros que +ocorrem de forma sincronizada e assíncrona. Expresso vem com um erro padrão +manipulador para que você não precise escrever seu próprio para começar. + +## Capturando Erros + +É importante garantir que Expresso pegue todos os erros que ocorrem enquanto +rodando manipuladores de rotas e intermediários. + +Erros que ocorrem no código síncrono dentro dos manipuladores de rota e middleware +não exigem trabalho extra. If synchronous code throws an error, then Express will +catch and process it. Por exemplo: + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Expresso irá pegar isso sozinho. +}); +``` + +Para erros retornados de funções assíncronas, invocados pelos manipuladores de rota +e intermediário, você deve passá-los para a função `next()`, onde o Express irá capturá-los a +e processá-los. Por exemplo: + +```js +app.get('/', (req, res, next) => { + fs. eadFile('/file-does-not-existente', (err, data) => { + if (err) { + next(err); // Passa os erros para o Express. + } else { + res. end(data); + } + }); +}); +``` + +Começando pelo Express 5, roteadores e intermediários que retornam um Promise +chamarão `next(value)` automaticamente quando eles rejeitarem ou lançarem um erro. +Por exemplo: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = await getUserById(req.params.id); + res.send(user); +}); +``` + +Se `getUserById` lança um erro ou rejeita, `next` será chamado com +o erro lançado ou o valor rejeitado. Se nenhum valor rejeitado for fornecido, `next` +será chamado com um objeto de erro padrão fornecido pelo roteador Express. + +Se você passar qualquer coisa para a função `next()` (exceto a string `'route'`), +Expressa que a requisição atual é um erro e irá pular quaisquer funções +restantes que não sejam de manipulação de erros e middleware. + +Se o callback em uma sequência não fornecer dados, somente erros, você pode simplificar +este código da seguinte forma: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +No exemplo acima, `next` é fornecido como o callback para `fs.writeFile`, +que é chamado com ou sem erros. Se não houver erro, o segundo receptor +é executado, caso contrário as pegadas do Express e processa o erro. + +Você deve capturar os erros que ocorrem em código assíncrono invocado pelos manipuladores da rota ou +middleware e passá-los para o Expresso para processamento. Por exemplo: + +```js +app.get('/', (q, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + ext(err); + } + }, 100); +}); +``` + +O exemplo acima usa um bloco `tentar... catch` para capturar erros no código assíncrono +e passá-los para o Express. Se o bloco `tentar...catch` +fosse omitido, Express não pegaria o erro, uma vez que ele não faz parte do código de manipulador +síncrono. + +Use promessas para evitar a sobrecarga do bloco `tentar... capturar` ou ao usar funções +que retornam promessas. Por exemplo: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + . hen(() => { + joga novo Error('BROKEN'); + }) + . atch(next); // Erros serão passados para o Express. +}); +``` + +Since promises automatically catch both synchronous errors and rejected promises, +you can simply provide `next` as the final catch handler and Express will catch errors, +because the catch handler is given the error as the first argument. + +Você também pode usar uma cadeia de manipuladores para confiar em erro síncrono +de recuperação, reduzindo o código assíncrono a algo trivial. Por exemplo: + +```js +app.get('/', [ + função (req, res, ext) { + fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals. ata = data; + ext(err); + }); + }, + função (req, res) { + res. ocals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +O exemplo acima tem algumas declarações triviais da chamada `readFile` +. If `readFile` causes an error, then it passes the error to Express, otherwise you +quickly return to the world of synchronous error handling in the next handler +in the chain. Então, o exemplo acima tenta processar os dados. Se isso falhar, o manipulador de erro +síncrono irá pegá-lo. Se você tivesse feito este processamento dentro do +o callback `readFile`, então o aplicativo poderia sair e o erro Express +manipuladores não executariam. + +Seja qual for o método que você usar, se você quer que os manipuladores de erro Expressos sejam chamados para dentro e o aplicativo +para sobreviver, você deve garantir que o Expresso receba o erro. + +## O manipulador de erro padrão + +Expresso vem com um manipulador de erro embutido que cuida de quaisquer erros que possam ser encontrados no aplicativo. Esta função de middleware com erros padrão é adicionada no final da função middleware stack. + +Se você passar um erro para `next()` e não lidar com ele em um erro personalizado +handler, será tratado pelo manipulador de erro embutido; o erro será +escrito no cliente com o rastreamento de pilha. O rastreamento da pilha não está incluído +no ambiente de produção. + + + +Defina a variável de ambiente `NODE_ENV` como `production`, para executar o aplicativo em modo de produção. + + + +Quando um erro é escrito, a seguinte informação é adicionada a +resposta: + +* O `res.statusCode` é definido em `err.status` (ou `err.statusCode`). Se + este valor estiver fora do intervalo de 4xx ou 5xx, ele será definido como 500. +* A mensagem 'res.statusMessage' é definida de acordo com o código de status. +* O corpo será o HTML da mensagem do código de status quando em produção + ambiente, caso contrário será `err.stack`. +* Qualquer cabeçalho especificado em um objeto `err.headers`. + +Se você chamar `next()` com um erro depois que você começou a escrever a +resposta (por exemplo, se você encontrar um erro ao transmitir a resposta +ao cliente), o Express default error handler fecha a conexão +e falha na solicitação. + +Então, quando você adicionar um manipulador de erro personalizado, você deve delegar para +o manipulador de erro padrão Express, quando os cabeçalhos +já foram enviados para o cliente: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Observe que o manipulador de erro padrão pode ser acionado se você chamar `next()` com um erro +no seu código mais de uma vez. Mesmo que um erro personalizado de manipulação de middleware esteja no lugar. + +Outro erro de manipulação de middleware pode ser encontrado em [Express middleware](/en/resources/middleware). + +## Escrevendo manipuladores de erros + +Definir funções intermediárias de manipulação de erros da mesma forma que outras funções de middleware, +exceto funções de manipulação de erro possuem quatro argumentos ao invés de três: +`(err, req, res, next)`. Por exemplo: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Algo quebrado!'); +}); +``` + +Você define o middleware de erro duramente, depois de outro `app.use()` e roteia chamadas; por exemplo: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser. rlencoded({ + extendido: true, + }) +); +app.use(bodyParser.json()); +app. se(methodOverride()); +app.use((err, req, res, next) => { + // lógica +}); +``` + +As respostas de dentro de uma função middleware podem estar em qualquer formato, como uma página de erro HTML, uma mensagem simples ou uma string JSON. + +Para fins de estrutura organizacional (e de nível superior), você pode definir +várias funções de middleware com manipulação de erros, tanto quanto você poderia com funções de intermediário +regulares. Por exemplo, para definir um manipulador de erro +para solicitações feitas usando `XHR` e aqueles sem: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app. se( + bodyParser.urlencoded({ + extendido: true, + }) +); +app. se(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +In this example, the generic `logErrors` might write request and +error information to `stderr`, for example: + +```js +function logErrors(err, req, res, ext) { + console.error(err.stack); + next(err); +} +``` + +Também neste exemplo, `clientErrorHandler` é definido como segue; neste caso, o erro é explicitamente passado para o próximo. + +Observe que quando *não* estiver chamando "próximo" em uma função de manipulação de erros, você é responsável por escrever (e terminar) a resposta. Caso contrário, esses pedidos ficarão "pendentes" e não serão elegíveis para a recolha de lixo. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500). end({ error: 'Algo falhou!' }); + } else { + next(err); + } +} +``` + +Implementar a função "catch-all" `errorHandler` da seguinte forma (por exemplo): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +Se você tiver um gerenciador de rotas com múltiplas funções de retorno de chamada, você pode usar o parâmetro `rota` para pular para o próximo manipulador de rota. Por exemplo: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user. asPaid) { + // continue lidando com esta requisição + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent. ind((err, doc) => { + se (err) retornar next(err); + res. son(doc); + }); + } +); +``` + +Neste exemplo, o manipulador `getPaidContent` será ignorado, mas quaisquer manipuladores restantes em `app` para `/a_route_behind_paywall` continuariam sendo executados. + + + +Chama para `next()` e `next(err)` indicam que o manipulador atual está completo e em que estado. +`next(err)` pulará todos os manipuladores restantes na cadeia, exceto aqueles que estão configurados para +lidar com erros conforme descrito acima. + + diff --git a/src/content/docs/pt-br/4x/guide/overriding-express-api.md b/src/content/docs/pt-br/4x/guide/overriding-express-api.md new file mode 100644 index 0000000000..d5ceef01af --- /dev/null +++ b/src/content/docs/pt-br/4x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Sobrescrevendo a API Expresso +description: Descubra como personalizar e estender a API do Express.js substituindo métodos e propriedades nos objetos de solicitação e resposta usando protótipos. +--- + +A API do Expresso consiste de vários métodos e propriedades nos objetos de solicitação e resposta. Estas são herdadas pelo protótipo. Há dois pontos de extensão para a API Express: + +1. Os protótipos globais em `express.request` e `express.response`. +2. Protótipos específicos de aplicativo em `app.request` e `app.response`. + +Alterar os protótipos globais afetará todos os aplicativos do Express carregados no mesmo processo. Se desejar, alterações podem ser feitas especificamente no aplicativo, alterando apenas os protótipos específicos do aplicativo após criar um novo aplicativo. + +## Métodos + +Você pode substituir a assinatura e o comportamento dos métodos existentes com o seu próprio, atribuindo uma função personalizada. + +A seguir é um exemplo de substituição do comportamento de [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +A implementação acima altera completamente a assinatura original de `res.sendStatus`. Agora aceita um código de estado, um tipo de codificação e a mensagem a ser enviada ao cliente. + +O método sobrescrito agora pode ser usado dessa maneira: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## propriedades + +As propriedades da API Expresso também são: + +1. Propriedades atribuídas (ex: `req.baseUrl`, `req.originalUrl`) +2. Definido como getters (ex: `req.secure`, `req.ip`) + +Uma vez que as propriedades da categoria 1 são dinamicamente atribuídas aos objetos `request` e `response` no contexto do ciclo atual de resposta de solicitação, seu comportamento não pode ser substituído. + +As propriedades da categoria 2 podem ser substituídas usando a API de extensões de API Express. + +O código a seguir reescreve como o valor de `req.ip` deve ser derivado. Agora, ele simplesmente retorna o valor do cabeçalho de solicitação `Client-IP`. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Protótipo + +Para fornecer a API Express, os objetos de solicitação/resposta passados para Express (via `app(req, res)`, por exemplo) precisam herdar do mesmo tipo de cadeia. Por padrão, isto é `http.IncomingRequest.prototype` para a solicitação e `http.ServerResponse.prototype` para a resposta. + +Se necessário, recomenda-se que isso seja feito apenas a nível da aplicação, e não a nível global. Além disso, tenha cuidado para que o protótipo usado corresponda à funcionalidade o mais próximo possível dos protótipos padrão. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/pt-br/4x/guide/routing.mdx b/src/content/docs/pt-br/4x/guide/routing.mdx new file mode 100644 index 0000000000..c8e9e2d7a3 --- /dev/null +++ b/src/content/docs/pt-br/4x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Roteamento +description: Aprenda a definir e usar rotas em aplicações Express.js, incluindo métodos de rota, caminhos de rota, parâmetros e usando o roteador para roteamento modular. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* refere-se a como os endpoints de um aplicativo (URIs) respondem às solicitações do cliente. +Para uma introdução ao roteamento, veja [Roteamento básico](/en/starter/basic-routing). + +Você define roteamento usando métodos do objeto Express `app` que correspondem aos métodos HTTP; +por exemplo, `app. et()` para lidar com solicitações GET e `app.post` para lidar com solicitações POST. Para obter uma lista completa, +ver [app.METHOD](/en/5x/api#app.METHOD). Você também pode usar o [app.all()](/en/5x/api#app.all) para lidar com todos os métodos HTTP e [app. se()](/en/5x/api#app.use) para +especifique middleware como função de retorno de chamada (Veja [Usando middleware](/en/guide/using-middleware) para detalhes). + +Esses métodos de roteamento especificam uma função de callback (às vezes chamada de "funções de manipulador") chamada quando a aplicação recebe uma solicitação para a rota especificada (endpoint) e método HTTP. Em outras palavras, o aplicativo "listas" para solicitações que correspondem com a(s) rota(s) e método(s) especificado(s), e quando ela detecta uma correspondência, ela chama a função de retorno de chamada especificado. + +Na verdade, os métodos de roteamento podem ter mais de uma função de callback como argumentos. +Com múltiplas funções de callback, é importante fornecer `next` como um argumento para a função de callback e então chamar `next()` dentro do corpo da função para liberar o controle +para a próxima callback. + +O código a seguir é um exemplo de uma rota muito básica. + +```js +const express = require('express'); +const app = express(); + +// responda com "olá mundo" quando for feita uma solicitação GET para a página inicial +app. et('/', (req, res) => { + res.send('hello world'); +}); +``` + +## Métodos de rota + +Um método de route é derivado de um dos métodos HTTP e é anexado a uma instância da classe 'express'. + +O código a seguir é um exemplo de rotas que são definidas para os métodos `GET` e `POST` para a raiz do aplicativo. + +```js +// GET method route +app.get('/', (req, res) => { + res.send('GET request to the homepage'); +}); + +// POST method route +app.post('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Expresso suporta métodos que correspondem a todos os métodos de requisição HTTP: `get`, `post`, e assim por diante. +Para uma lista completa, consulte [app.METHOD](/en/5x/api#app.METHOD). + +Há um método de roteamento especial, `app.all()`, usado para carregar funções de middleware em um caminho para os métodos de requisição HTTP. Por exemplo, o seguinte manipulador é executado para solicitações para a rota `"/secre"` usando `GET`, `POST`, `PUT`, `DELETE`, ou qualquer outro método de solicitação HTTP suportado no [módulo http](https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Acessando a seção secreta ...'); + next(); // passe o controle para o próximo manipulador +}); +``` + +## Caminho da rota + +Roteamento, em combinação com um método de solicitação, defina os pontos de extremidade em que as solicitações podem ser feitas. Caminhos de rota podem ser frases, padrões de strings ou expressões regulares. + + + +Expresso 5, os caracteres `? , `+`, `\*`, `[]`, e `()\` são tratados de forma diferente da versão +4, por favor, revise o [guia de migração](/en/guide/migrating-5#path-syntax) para mais informações. + + + + + +No modo expresso 4, caracteres de expressão regular como `$` precisam ser escapados com um `\`. + + + + + +Expresso usa [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) para corresponder à rota +caminhos; veja a documentação pay-to-regexp para todas as possibilidades em definir caminhos da rota. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) é uma ferramenta útil para +testar rotas Express, embora não suporte correspondência de padrões. + + + +strings de consulta não fazem parte do caminho de rota. + +### Caminhos de rota baseados em strings + +Este caminho de rota irá corresponder a solicitações para a rota raiz, `/`. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +Esse caminho de rota irá corresponder a solicitações para `/about`. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +Este caminho de rota irá corresponder a solicitações para `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Caminhos de rota baseados em padrões string + + + +Os padrões de string no Express 5 não funcionam mais. Por favor, consulte o [guia de migração +] (/en/guide/migrating-5#path-syntax) para obter mais informações. + + + +Este caminho de rota corresponderá a 'acd' e 'abcd'. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +Esse caminho de rota corresponderá a `abcd`, `abbcd`, `abbbcd`, e assim por diante. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +Esse caminho de rota irá coincidir com `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd`, e assim por diante. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +Esta rota de rota irá corresponder a `/abe` e `/abcde`. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Caminho baseado em expressões regulares + +Este caminho de rota combinará com qualquer coisa com "a" nele. + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +Esse caminho de rota irá coincidir com `borboleta` e `dragonfly`, mas não com `borboleta`, `dragonflyman`, e assim por diante. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Parâmetros de rota + +Parâmetros de rota são denominados segmentos de URL que são usados para capturar os valores especificados em sua posição na URL. Os valores capturados são preenchidos no objeto `req.params`, com o nome do parâmetro de rota especificado no caminho como suas respectivas chaves. + +``` +Caminho da rota: /users/:userId/books/:bookId +Solicitação URL: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +Para definir rotas com parâmetros de rota, simplesmente especifique os parâmetros de rota no caminho da rota, conforme mostrado abaixo. + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +O nome dos parâmetros de rota deve ser composto de "palavra caracteres" ([A-Za-z0-9_]). + + + +Como o hífen (`-`) e o ponto (`.`) são interpretados literalmente, eles podem ser usados juntamente com parâmetros de rota para fins úteis. + +``` +Caminho da rota: /fvots/:from-:to +Solicitação URL: http://localhost:3000/fvots/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Caminho da rota: /plantae/:genus.:species +Solicitação URL: http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "espécies": "persica" } +``` + + + +Expresso 5, Regexp caracteres não são suportados nos caminhos de rota, para mais informações por favor +consulte o [guia de migração](/en/guide/migrating-5#path-syntax). + + + +Para ter mais controle sobre a string exata que pode ser combinada por um parâmetro de rota, você pode acrescentar uma expressão regular entre parênteses (`()`): + +``` +Caminho da rota: /user/:userId(\d+) +Solicitar URL: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Porque a expressão regular geralmente faz parte de uma cadeia literal, certifique-se de escapar de quaisquer caracteres `\` +com uma barra invertida adicional, por exemplo `\d+`. + + + + +No Expresso 4.x, o caractere `*` em expressões regulares não é interpretado da maneira habitual. Como uma alternativa, use `{0,}` em vez de `*`. Isso provavelmente será corrigido no Express 5. + + +## Manipuladores de rota + +Você pode fornecer várias funções de retorno de chamada que se comportam como [middleware](/en/guide/using-middleware) para lidar com uma solicitação. A única exceção é que esses callbacks podem invocar `next('route')` para ignorar as chamadas restantes da rota. Você pode usar este mecanismo para impor pré-condições em uma rota, então passe controle para rotas subsequentes se não houver motivo para prosseguir com a rota atual. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params. d === '0') { + return next('rota'); + } + res. end(`Usuário ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('ID especial para o ID de usuário 0'); +}); +``` + +Neste exemplo: + +* `GET /user/5` → tratado pela primeira rota → envia "Usuário 5" +* `GET /user/0` → primeira rota chama `next('rote')`, pulando para a próxima rota `/user/:id` correspondente + +Os manipuladores de rotas podem estar na forma de uma função, um array de funções ou combinações de ambos, como mostrado nos exemplos a seguir. + +Uma única função de retorno de chamada pode manipular uma rota. Por exemplo: + +```js +app.get('/example/a', (req, res) => { + res.send('Olá de A!'); +}); +``` + +Mais de uma função de retorno de chamada pode manipular uma rota (certifique-se de especificar o objeto `next`). Por exemplo: + +```js +app.get( + '/example/b', + (req, res, next) => { + console. og('a resposta será enviada pela próxima função. .'); + next(); + }, + (req, res) => { + res. end('Olá de B!'); + } +); +``` + +Um array de funções de retorno de chamada pode lidar com uma rota. Por exemplo: + +```js +const cb0 = function (req, res, next) { + console. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +const cb2 = function (req, res) { + res. end('Olá de C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +Uma combinação de funções independentes e matrizes de funções pode lidar com uma rota. Por exemplo: + +```js +const cb0 = function (req, res, next) { + console. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +aplicativo. et( + '/example/d', + [cb0, cb1], + (req, res, next) => { + console. og('a resposta será enviada pela próxima função. .'); + next(); + }, + (req, res) => { + res. end('Olá de D!'); + } +); +``` + +## Métodos de resposta + +Os métodos no objeto de resposta ('res') na tabela a seguir podem enviar uma resposta para o cliente e encerrar o ciclo de resposta de solicitação. Se nenhum destes métodos for chamado de um manipulador de redes, a solicitação do cliente será deixada em suspenso. + +| Método | Descrição: | +| --------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | Solicite que um arquivo seja baixado. | +| [res.end()](/en/5x/api#res.end) | Encerrar o processo de resposta. | +| [res.json()](/en/5x/api#res.json) | Enviar uma resposta JSON. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Envie uma resposta JSON com suporte a JSONP. | +| [res.redirect()](/en/5x/api#res.redirect) | Redirecionar uma requisição. | +| [res.render()](/en/5x/api#res.render) | Renderizar um modelo de visão. | +| [res.send()](/en/5x/api#res.send) | Envie uma resposta de vários tipos. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Envia um arquivo como uma transmissão octet. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Defina o código de status da resposta e envie sua representação de string como o corpo da resposta. | + +## app.route() + +Você pode criar manipuladores de rotas em cadeia para um caminho de rota usando `app.route()`. +Como o caminho é especificado em um único local, é útil criar rotas modulares, assim como reduzir a redundância e os tipos. Para obter mais informações sobre rotas, consulte: [documentação de roteador](/en/5x/api#router). + +Aqui está um exemplo de manipuladores de rota encadeados que são definidos usando `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res. end('Recebe um livro aleatório'); + }) + . ost((req, res) => { + res.send('Adicionar um livro'); + }) + . ut((req, res) => { + res.send('Atualizar o livro'); +}); +``` + +## expressão.Roteador + +Use a classe 'express.Router' para criar módulo, manipuladores de rotas montáveis. Uma instância `Router` é um sistema completo de middleware e roteamento; por este motivo, é muitas vezes referido como um "mini-app". + +O exemplo a seguir cria um roteador como um módulo, carrega uma função middleware nele define algumas rotas e monta o módulo do roteador em um caminho no aplicativo principal. + +Crie um arquivo de roteador chamado `birds.js` no diretório de aplicativos, com o seguinte conteúdo: + +```js +const express = require('express'); +const router = express.Router(); + +// middleware that is specific to this router +const timeLog = (req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}; +router.use(timeLog); + +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Em seguida, carregue o módulo do roteador no aplicativo: + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +O aplicativo agora poderá lidar com pedidos para `/birds` e `/birds/about`, Além de chamar a função middleware `timeLog` que é específica da rota. + +Mas se a rota pai `/birds` tiver parâmetros de caminho, ela não será acessível por padrão nas sub-rotas. Para torná-lo acessível, você precisará passar a opção `mergeParams` para o construtor do roteador [reference](/en/5x/api#app.use). + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/pt-br/4x/guide/using-middleware.mdx b/src/content/docs/pt-br/4x/guide/using-middleware.mdx new file mode 100644 index 0000000000..c1e4bab642 --- /dev/null +++ b/src/content/docs/pt-br/4x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Usando o middleware +description: Aprenda a usar o middleware em aplicativos do Express.js, incluindo o nível de aplicativos e o middleware, manipulação de erros e integração de intermediários de terceiros. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express é uma web framework de roteamento e middleware que tem a funcionalidade mínima de sua própria funcionalidade: Um aplicativo Express é essencialmente uma série de chamadas de função middleware. + +Middleware_ são funções que têm acesso ao [objeto de requisição](/en/5x/api#req) (`req`), a [objeto de resposta](/en/5x/api#res) (`res`) e a próxima função de middleware no ciclo de resposta de solicitação do aplicativo. A próxima função de middleware é comumente denotada por uma variável chamada `next`. + +As funções do Middleware podem executar as seguintes tarefas: + +* Execute qualquer código. +* Fazer alterações na solicitação e nos objetos de resposta. +* Encerrar o ciclo de solicitação-resposta. +* Chame a próxima função middleware na pilha. + +Se a função middleware atual não encerra o ciclo de resposta de solicitação, ela deve chamar `next()` para passar o controle para a próxima função middleware. Caso contrário, o pedido ficará pendurado. + +Um aplicativo Express pode usar os seguintes tipos de middleware: + +* [Meio do aplicativo](#middleware.application) +* [Meio do roteador](#middleware.router) +* [Middleware com erro](#middleware.error-handling) +* [middleware](#middleware.built-in) +* [Middleware de terceiros](#middleware.third-party) + +Você pode carregar o nível de aplicação e middleware de nível de roteador com um caminho de montagem opcional. +Você também pode carregar uma série de funções intermediárias juntas, o que cria uma sub-pilha do sistema intermediário em um ponto de montagem. + +## Midddleware no nível de aplicação + +Vincular aplicativo de nível middleware a uma instância do [objeto de aplicativo](/en/5x/api#app) usando o `app.use()` e `app. Funções ETHOD()`, onde `METHOD` é o método HTTP da solicitação que a função middleware lida (como GET, PUT, ou POST) em minúsculas. + +Este exemplo mostra uma função middleware sem caminho de montagem. A função é executada toda vez que o aplicativo recebe uma solicitação. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +Este exemplo mostra uma função middleware montada no caminho `/user/:id`. A função é executada para qualquer tipo de solicitação HTTP +no caminho `/user/:id`. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Tipo de requisição:', req.method); + next(); +}); +``` + +Este exemplo mostra uma rota e sua função de manipulador (sistema de middleware). A função lida com requisições GET para o caminho `/user/:id`. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +Aqui está um exemplo de carregar uma série de funções intermediárias em um ponto de montagem, com um caminho de montagem. +Isto ilustra um sub-stack de middleware que imprime informação de solicitação para qualquer tipo de solicitação de HTTP no caminho `/user/:id`. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Solicitação de URL:', req. riginalUrl); + next(); + }, + (req, res, next) => console { + . og('Tipo de requisição:', req.method); + next(); + } + +``` + +Os gerenciadores de rotas permitem que você defina várias rotas para um caminho. O exemplo abaixo define duas rotas para solicitações GET para o caminho `/user/:id`. A segunda via não causará quaisquer problemas, mas nunca será chamada, porque a primeira via termina o ciclo de resposta aos pedidos. + +Este exemplo mostra uma sub-pilha de middleware que lida com requisições GET para o caminho `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req. arams.id); + next(); + }, + (req, res, next) => { + res. end('Informações do usuário'); + } +); + +// manipulador para o caminho /user/:id, que imprime o ID do usuário +aplicativo. et('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +Para ignorar o resto das funções de middleware a partir de uma pilha de middleware do roteador, chame `next('route')` para passar o controle para a próxima rota. + + + +`next('rota')` funcionará apenas em funções de middleware que foram carregadas usando as funções +`app.METHOD()` ou `router.METHOD()`. + + + +Este exemplo mostra uma sub-pilha de middleware que lida com requisições GET para o caminho `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next route + if (req.params.id === '0') next('route'); + // otherwise pass the control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // send a regular response + res.send('regular'); + } +); + +// handler for the /user/:id path, which sends a special response +app.get('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +O Middleware também pode ser declarado em um array para reutilizabilidade. + +Este exemplo mostra um array com um sub-stack de middleware que lida com requisições GET para o caminho `/user/:id` + +```js +function logOriginalUrl(req, res, próximo) { + console.log('Solicitação URL:', req. riginalUrl); + next(); +} + +function logMethod(req, res, ext) { + console.log('Request Type:', req. ethod); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app. et('/user/:id', logStuff, (req, res, next) => { + res.send('Usuário Info'); +}); +``` + +## Midddleware nível de roteamento + +O middleware de roteador funciona da mesma maneira que o middleware no nível de aplicativo, exceto que está vinculado a uma instância de `express.Router()`. + +```js +const router = express.Router(); +``` + +Carregue o middleware no nível de roteador usando as funções `router.use()` e `router.METHOD()`. + +O código a seguir replica o sistema middleware que é mostrado acima para o middleware no nível de aplicativos, usando o middleware no nível de roteador: + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// a middleware function with no mount path. This code is executed for every request to the router +router.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); + +// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path +router.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); + +// a middleware sub-stack that handles GET requests to the /user/:id path +router.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next router + if (req.params.id === '0') next('route'); + // otherwise pass control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // render a regular page + res.render('regular'); + } +); + +// handler for the /user/:id path, which renders a special page +router.get('/user/:id', (req, res, next) => { + console.log(req.params.id); + res.render('special'); +}); + +// mount the router on the app +app.use('/', router); +``` + +Para ignorar o resto das funções de middleware do roteador, chame `next('router')` +para passar o controle de volta para fora da instância do roteador. + +Este exemplo mostra uma sub-pilha de middleware que lida com requisições GET para o caminho `/user/:id`. + +```js +const express = require('express'); +const app = express(); +const router = expressos. + +// prefixa o roteador com uma verificação e resgate quando necessário +roteador. se((req, res, ext) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router. et('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// usa o roteador e 401 tudo que cai através do app +. se('/admin', roteador, (req, res) => { + res.sendStatus(401); +}); +``` + +## Midddleware com erro manipulado + + + +O middleware com erros de manipulação sempre toma *quatro* argumentos. Você deve fornecer quatro argumentos para +identificá-lo como uma função de middleware manipulação de erros. Mesmo se você não precisar usar o objeto `next` +, você deve especificá-lo para manter a assinatura. Caso contrário, o objeto `próximo` será +interpretado como um middleware regular e irá falhar em lidar com erros. + + + +Definir funções intermediárias de manipulação de erros da mesma forma que outras funções de middleware, exceto quatro argumentos em vez de três, especificamente com a assinatura `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Algo quebrado!'); +}); +``` + +Para detalhes sobre o middleware, consulte: [Error handling](/en/guide/error-handling). + +## Midddleware integrado + +A partir da versão 4.x, o Express não depende mais do [Connect](https://github.com/senchalabs/connect). O middleware +funções que foram previamente incluídas com Express estão agora em módulos separados; consulte [a lista de funções de middleware](https://github.com/senchalabs/connect#middleware). + +O Express tem as seguintes funções de middleware incorporadas: + +* [express.static](/en/5x/api#express.static) serve como arquivos estáticos, como arquivos HTML, imagens e assim por diante. +* [express.json](/en/5x/api#express.json) analisa solicitações recebidas com carga JSON. **NOTA: Disponível com Expresso 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) analisa solicitações recebidas com payloads codificados por URL. **NOTA: Disponível com Expresso 4.16.0+** + +## Midddleware de terceiros + +Usar middleware de terceiros para adicionar funcionalidades a aplicativos Express. + +Instale o módulo Node.js para a funcionalidade requerida e, em seguida, carregue-o em seu aplicativo ao nível do aplicativo ou no nível do roteador. + +O exemplo a seguir ilustra a instalação e o carregamento da função middleware de análise de cookie-parser\`. + +```bash +$ npm install cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// carrega o middleware +app.use(cookieParser()); +``` + +Para uma lista parcial de funções intermediárias de terceiros que são comumente usadas com Express, veja: [middleware de terceiros](../resources/middleware). diff --git a/src/content/docs/pt-br/4x/guide/using-template-engines.mdx b/src/content/docs/pt-br/4x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..ff8b9c8e16 --- /dev/null +++ b/src/content/docs/pt-br/4x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Usando mecanismos de template com o Express +description: Descubra como integrar e usar mecanismos de modelos como Pug, Handlebars, e EJS com Express.js para renderizar páginas HTML dinâmicas de forma eficiente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Um *motor de template* permite que você use arquivos de template estáticos na sua aplicação. At runtime, the template engine replaces +variables in a template file with actual values, and transforms the template into an HTML file sent to the client. +Esta abordagem torna mais fácil projetar uma página HTML. + +O [gerador de aplicação Expressa](/en/starter/generator) usa [Pug](https://pugjs.org/api/getting-started.html) como seu padrão, mas também apoia [Handlebars](https://www.npmjs.com/package/handlebars), e [EJS](https://www.npmjs.com/package/ejs), entre outros. + +Para renderizar arquivos de template, defina as seguintes [propriedades de configuração da aplicação](/en/4x/api#app.set), no `app.js` padrão criado pelo gerador: + +* `views`, o diretório onde se localizam os arquivos de template. Ex: `app.set('views', './views')`. + Isto é padrão para o diretório `views` no diretório raiz do aplicativo. +* `ver engenho`, o mecanismo de modelos a ser usado. Por exemplo, para usar o motor de template Pug: `app.set('engenharia de visualização', 'pug')`. + +Então instale o correspondente mecanismo de template do npm pacote; por exemplo, para instalar o Pug: + +```bash +$ npm install pug --save +``` + + +Mecanismos de template compatíveis com o código, como Pug exporta uma função chamada `__express(filePath, opções, callback)`, +que `res.render()` chama para renderizar o código de template. + +Alguns motores de modelos não seguem esta convenção. A biblioteca [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +segue esta convenção mapeando todos os mecanismos de modelo populares de Node.js e, portanto, funciona perfeitamente dentro do Express. + + + +Depois que o motor de visualização estiver definido, você não precisa especificar o motor ou carregar o módulo de mecanismo de modelo no seu aplicativo; +Expresso carrega o módulo internamente, por exemplo: + +```js +app.set('mecanismo de visão', 'pug'); +``` + +Em seguida, crie um arquivo de template Pug chamado `index.pug` no diretório `views`, com o seguinte conteúdo: + +```pug +html + head + title= title + corpo + h1= mensagem +``` + +Crie uma rota para renderizar o arquivo `index.pug`. Se a propriedade `view engine` não estiver definida, +você deve especificar a extensão do arquivo `view`. Caso contrário, você pode omitir. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Ei', message: 'Olá lá!' }); +}); +``` + +Quando você faz uma solicitação à página inicial, o arquivo `index.pug` será processado como HTML. + +O cache do motor de exibição não armazena o conteúdo da saída do modelo, apenas o modelo subjacente em si. A visualização ainda é renderizada novamente com todas as requisições, mesmo que o cache esteja ativo. diff --git a/src/content/docs/pt-br/4x/guide/writing-middleware.mdx b/src/content/docs/pt-br/4x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..3fb77ab014 --- /dev/null +++ b/src/content/docs/pt-br/4x/guide/writing-middleware.mdx @@ -0,0 +1,239 @@ +--- +title: Escrever middleware para uso nos aplicativos Express +description: Aprenda a escrever funções de middleware personalizadas para aplicativos Express.js, incluindo exemplos e melhores práticas para melhorar a resolução de pedidos e respostas. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Middleware_ são funções que têm acesso ao [objeto de requisição](/en/5x/api#req) (`req`), a [objeto de resposta](/en/5x/api#res) (`res`) e a função `next` no ciclo de resposta de solicitação do aplicativo. A função `próxima` é uma função no roteador Expresso que, quando invocado, executa o intermediário sucedendo ao intermediário atual. + +As funções do Middleware podem executar as seguintes tarefas: + +* Execute qualquer código. +* Fazer alterações na solicitação e nos objetos de resposta. +* Encerrar o ciclo de solicitação-resposta. +* Chame o próximo middleware na pilha. + +Se a função middleware atual não encerra o ciclo de resposta de solicitação, ela deve chamar `next()` para passar o controle para a próxima função middleware. Caso contrário, o pedido ficará pendurado. + +A figura a seguir mostra os elementos de uma chamada de função middleware: + +
+ + + + + +
+Elementos de uma chamada de função middleware + +
método HTTP para o qual se aplicam as funções middleware.
+ +
+ Caminho (rota) para o qual a função middleware se aplica. +
+ +
+ A função middleware. +
+ +
+ Argumento de retorno para a função middleware, chamado "próximo" por convenção. +
+ +
+ HTTP resposta argumento para a função middleware, chamada de "res" pela convenção + . +
+ +
HTTP request argumento para a função middleware, chamado de "req" pela convenção.
+
+
+ +Começando com as funções de middleware Express, funções de intermediário que retornam uma Promessa chamarão `próximo(valor)` quando eles rejeitarem ou lançarem um erro. `next` será chamado com o valor rejeitado ou o erro lançado. + +## Exemplo + +Aqui está um exemplo de uma aplicação simples "Hello World" Express. +The remainder of this article will define and add three middleware functions to the application: +one called `myLogger` that prints a simple log message, one called `requestTime` that +displays the timestamp of the HTTP request, and one called `validateCookies` that validates incoming cookies. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +### Função Middleware myLogger + +Aqui está um exemplo simples de uma função de middleware chamada "myLogger". Essa função apenas imprime +"LOGGGED" quando uma solicitação para o aplicativo passa por ela. A função middleware está atribuída a uma variável +chamada `myLogger`. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGGED'); + next(); +}; +``` + + + +Observe a chamada acima para `next()`. Chamar esta função chama a próxima função de middleware em +o aplicativo. A função `next()` não é parte do Node. s ou API Expressa, mas é o terceiro argumento +que é passado para a função middleware. A função `next()` pode ser nomeada qualquer coisa, +mas por convenção é sempre chamada de "next". Para evitar confusões, utilize sempre esta convenção. + + + +Para carregar a função middleware, chame `app.use()`, especificando a função middleware. +Por exemplo, o código a seguir carrega a função `myLogger` middleware antes da rota para o caminho raiz (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console. og('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +Toda vez que o aplicativo recebe uma solicitação, ele imprime a mensagem "LOGGED" no terminal. + +A ordem do carregamento do middleware é importante: as funções de middleware que são carregadas primeiro também são executadas primeiro. + +Se o `myLogger` é carregado após a rota para o caminho raiz, a solicitação nunca chega a ela e o aplicativo não imprime "LOGGED", porque o gerenciador de rotas do caminho raiz termina o ciclo de resposta-requisição. + +A função middleware `myLogger` simplesmente imprime uma mensagem, então passa a requisição para a próxima função de middleware na pilha chamando a função `next()`. + +### Tempo de solicitação de função Middleware + +Em seguida, vamos criar uma função middleware chamada "requestTime" e adicionar uma propriedade chamada `requestTime` +ao objeto solicitado. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +O aplicativo agora usa a função middleware `requestTime`. Além disso, a função de retorno de chamada da rota raiz usa a propriedade que a função middleware adiciona a `req` (o objeto de solicitação). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req. equestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +aplicativo. et('/', (req, res) => { + let responseText = 'Olá Mundo!
'; + responseText += `Solicitado em: ${req.requestTime}`; + res. end(responseText); +}); + +app.listen(3000); +``` + +Quando você faz uma solicitação na raiz do aplicativo, o aplicativo agora mostra a marcação de hora da sua solicitação no navegador. + +### Função Middleware validateCookies + +Finalmente, vamos criar uma função de middleware que valida os cookies recebidos e envia uma resposta de 400 se cookies forem inválidos. + +Aqui está uma função de exemplo que valida cookies com um serviço assíncrono externo. + +```js +função assíncrona cookieValidator(cookies) { + tente { + aguarde externamenteCookie(cookies.testCookie); + } pesque { + throw new Error('Cookies inválidos'); + } +} +``` + +Aqui, usamos o [`cookie-parser`](/en/resources/middleware/cookie-parser) middleware para analisar cookies recebidos do objeto `req` e passá-los para a nossa função `cookieValidator`. O middleware 'validateCookies' retorna a promessa de que, após a rejeição, irá automaticamente acionar o nosso manipulador de erros. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('. cookieValidator'); + +const app = express(); + +função async validateCookies(req, res, next) { + aguarde cookieValidator(req. ookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// manipulador de erro +. se((err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Observe como `next()` é chamado depois `await cookieValidator(req.cookies)`. Isto garante que se +`cookieValidator` resolver, o próximo middleware na pilha será chamado. Se você passar qualquer coisa +para a função `next()` (exceto a string `'route'` ou `'router'`), Expresse que a solicitação +atual é um erro e pulará quaisquer funções que ainda não sejam de manipulação de erros e de middleware +. + + + +Como você tem acesso ao objeto de solicitação, o objeto de resposta, a próxima função de middleware na pilha, e todo o nó. s API, as possibilidades com funções de middleware são infinitas. + +Para mais informações sobre Express middleware, veja: [Usando Express middleware](/en/guide/using-middleware). + +## middleware configurável + +Se precisar de seu middleware para ser configurável, exporte uma função que aceite um objeto de opções ou outros parâmetros, que então retorna a implementação intermediária com base nos parâmetros de entrada. + +Arquivo: `meu-middleware.js` + +```js +Módulo xports = função (opcions) { + return function (req, next) { + // Implementa a função middleware baseada no objeto de opções + next(); + }; +}; +``` + +O middleware agora pode ser usado como mostrado abaixo. + +```js +const mw = require('./meu-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Consulte [cookie-session](https://github.com/expressjs/cookie-session) e [compression](https://github.com/expressjs/compression) para ver exemplos de intermediário configurável. diff --git a/src/content/docs/pt-br/4x/starter/basic-routing.mdx b/src/content/docs/pt-br/4x/starter/basic-routing.mdx new file mode 100644 index 0000000000..ea9db985e3 --- /dev/null +++ b/src/content/docs/pt-br/4x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Roteamento básico +description: Aprenda os fundamentos do roteamento em aplicações Express.js, incluindo como definir rotas, lidar com métodos HTTP e criar manipuladores de rotas para seu servidor web. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* refere-se a determinar como uma aplicação responde a uma solicitação do cliente para um ponto final específico, que é um URI (ou caminho) e um método de requisição HTTP específico (GET, POST, e assim por diante). + +Cada rota pode ter uma ou mais funções de manipulador, que são executadas quando a rota é correspondente. + +A definição de rota aceita a seguinte estrutura: + +```js +app.METHOD(PATH, MUITO); +``` + +Onde: + +* `app` é uma instância de `express`. +* `METHOD` é um [método de solicitação HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), em minúsculas. +* O `PATH` é um caminho no servidor. +* `HANDLER` é a função executada quando a rota é correspondente. + + + +This tutorial assumes that an instance of `express` named `app` is created and the server is +running. Se você não estiver familiarizado com a criação de um aplicativo e iniciando-o, consulte Olá mundo +exemplo. + + + +Os exemplos seguintes ilustram a definição de rotas simples. + +Responda com `Olá Mundo!` na página inicial: + +```js +app.get('/', (req, res) => { + res.send('Olá Mundo!'); +}); +``` + +Responder a uma solicitação POST na rota raiz (`/`), a página inicial do aplicativo: + +```js +app.post('/', (req, res) => { + res.send('Tem uma solicitação POST'); +}); +``` + +Responda a uma solicitação PUT para a rota `/user`: + +```js +app.put('/user', (req, res) => { + res.send('Tem uma solicitação de PUT em/user'); +}); +``` + +Responder a uma solicitação de DELETE para a rota `/user`: + +```js +app.delete('/user', (req, res) => { + res.send('Tem uma solicitação de DELETE em/user'); +}); +``` + +Para mais detalhes sobre roteamento, consulte o [guia de roteamento](/en/guide/routing). diff --git a/src/content/docs/pt-br/4x/starter/examples.mdx b/src/content/docs/pt-br/4x/starter/examples.mdx new file mode 100644 index 0000000000..a4dfced43d --- /dev/null +++ b/src/content/docs/pt-br/4x/starter/examples.mdx @@ -0,0 +1,45 @@ +--- +title: Exemplos expressos +description: Explore uma coleção de exemplos de aplicativos do Express.js cobrindo vários casos de uso, integrações e configurações avançadas para ajudá-lo a aprender e construir seus projetos. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Autenticação com login e senha +* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - negociação de conteúdo HTTP +* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Trabalhando com sessões baseadas em cookies +* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Trabalhando com cookies +* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transferindo arquivos para o cliente +* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Trabalhando com template JavaScript embutido (ejs) +* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Criando páginas de erro +* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Trabalhando com um middleware de erro +* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Manipulador de requisições simples +* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown como mecanismo de modelo +* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Trabalhando com vários roteadores Expressos +* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - controladores do estilo MVC +* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Rastreando atividade de usuário online com pacotes `online` e `redis` +* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Trabalhando com parâmetros de rotas +* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Várias operações HTTP no mesmo recurso +* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organização de rotas usando um mapa +* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Trabalhando com sistema de middleware +* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizando rotas por recurso +* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Pesquisa API +* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - Sessões de usuário +* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Servendo arquivos estáticos +* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Trabalhando com hosts virtuais +* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Renderizando visualizações dinamicamente +* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Salvando dados no objeto da solicitação entre chamadas de middleware +* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Serviço de API simples + +## Exemplos adicionais + +Estes são alguns exemplos adicionais com integrações mais extensas. + + + Esta informação refere-se a sites de terceiros, produtos ou módulos que não são mantidos pela equipe + Expressjs. Listar aqui não constitui um endosso ou recomendação da equipe de projeto + Expressjs. + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Aplicativo Fullstack com Express and Next.js usando [Prisma](https://www.npmjs.com/package/prisma) como ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - API REST com Express in TypeScript usando [Prisma](https://www.npmjs.com/package/prisma) como ORM diff --git a/src/content/docs/pt-br/4x/starter/faq.md b/src/content/docs/pt-br/4x/starter/faq.md new file mode 100644 index 0000000000..8af6c95239 --- /dev/null +++ b/src/content/docs/pt-br/4x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: Perguntas Frequentes +description: Encontre respostas para perguntas frequentes sobre Express.js, incluindo tópicos sobre a estrutura do aplicativo, modelos, autenticação, mecanismos de modelo, tratamento de erros e muito mais. +--- + +## Como eu devo estruturar meu aplicativo? + +Não há uma resposta definitiva a esta questão. A resposta depende +da escala do seu aplicativo e da equipe que está envolvida. Para ser o mais flexível possível, +flexível, Express não faz suposições em termos de estrutura. + +Rotas e outras lógicas específicas do aplicativo podem viver em quantos arquivos +você quiser, em qualquer estrutura de diretório que preferir. View the following +examples for inspiration: + +- [Lista de rotas](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Mapa de rotas](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Além disso, existem extensões para o Express, que simplificam alguns desses padrões: + +- [Roteamento de recursos](https://github.com/expressjs/express-resource) + +## Como faço para definir modelos? + +Expresso não tem noção de um banco de dados. This concept is +left up to third-party Node modules, allowing you to +interface with nearly any database. + +Veja [LoopBack](http://loopback.io) para um framework baseado em Express que é centralizado em torno de modelos. + +## Como posso autenticar os usuários? + +Authentication is another opinionated area that Express does not +venture into. Você pode usar qualquer esquema de autenticação desejado. +Para um esquema simples de nome de usuário/senha, consulte [este exemplo](https://github.com/expressjs/express/tree/master/examples/auth). + +## Quais mecanismos de template suporta o Expresso? + +Expresso suporta qualquer mecanismo de modelos que esteja em conformidade com a assinatura `(caminho, moradores, callback)`. +Para normalizar interfaces do motor de modelos e cache de cache, veja o projeto +[consolidate.js](https://github.com/visionmedia/consolidate.js) +para suporte. Motores de modelos não listados ainda podem suportar a assinatura Express. + +Para obter mais informações, consulte [Usando mecanismos de modelo com Express](/en/guide/using-template-engines). + +## Como lidamos com 404 respostas? + +Em Express, respostas 404 não são resultado de um erro, então +o middleware de erro não as capturará. This behavior is +because a 404 response simply indicates the absence of additional work to do; +in other words, Express has executed all middleware functions and routes, +and found that none of them responded. All you need to +do is add a middleware function at the very bottom of the stack (below all other functions) +to handle a 404 response: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Adicione rotas dinamicamente em tempo de execução em uma instância de `express.Router()` +para que as rotas não sejam substituídas por uma função middleware. + +## Como faço para configurar um manipulador de erro? + +Você define o middleware com erros de manipulação da mesma forma que outros middleware, +exceto com quatro argumentos em vez de três; especificamente com a assinatura `(err, req, res, próxima)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Para obter mais informações, consulte [Manipulação de erro](/en/guide/error-handling). + +## Como faço para tornar HTML simples? + +Você não! Não há necessidade de "render" HTML com a função `res.render()`. +Se você tiver um arquivo específico, use a função `res.sendFile()`. +Se você estiver servindo muitos assets de um diretório, use a função `express.static()` +middleware. + +## Qual versão do Node.js requer o Expresso? + +- [Expresso 4.x](/en/4x/api) requer Node.js 0.10 ou superior. +- [Express 5.x](/en/5x/api) requer Node.js 18 ou superior. diff --git a/src/content/docs/pt-br/4x/starter/generator.mdx b/src/content/docs/pt-br/4x/starter/generator.mdx new file mode 100644 index 0000000000..d2c4fade8e --- /dev/null +++ b/src/content/docs/pt-br/4x/starter/generator.mdx @@ -0,0 +1,127 @@ +--- +title: Gerador de aplicação expressa +description: Aprenda a usar a ferramenta gerador de aplicativo Express para criar rapidamente um esqueleto para seus aplicativos Express.js, otimização de configuração e configuração. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Use a ferramenta de gerador de aplicação, `express-generator`, para criar rapidamente um esqueleto de aplicação. + +Você pode executar o gerador de aplicação com o comando `npx` (disponível em Node.js 8.2.0). + +```bash +$ gerador de expressão npx +``` + +Para versões anteriores do Nó, instale o gerador de aplicativo como um pacote npm global e, em seguida, inicie-o: + +```bash +$ npm install -g express-generator +$ express +``` + +Exibe as opções de comando com a opção '-h': + +```bash +$ express -h + + Uso: express [options] [dir] + + Opções: + + -h, --help mostra informação de uso + --version mostra o número da versão + -e, --ejs add ejs engine suporte + --hbs add handlebars engine support + --pug add pug engine support + -H, --hogan adiciona hogan. s mecanismo suporta + --no-view gera sem o mecanismo de exibição + -v, --view add view support (ejs├hbs─jsėjade├jade├pug├twig├vash) (o padrão é jade) + -c, --css add stylesheet (menos:stylus➲ bússola) (o padrão é sem css) + --git add . itignore + -f, --force força em diretório não-vazio +``` + +Por exemplo, o seguinte cria um aplicativo Expresso chamado *myapp*. O aplicativo será criado em uma pasta chamada *myapp* no diretório de trabalho atual e o mecanismo de visualização será definido para Pug: + +```bash +$ express --view=pug meuapp + + create : meuapp + create : myapp/package.json + create : myapp/app. s + criam : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index. s + criar: meuapp/rotas/usuários. s + cria : myapp/public/stylesheets + create : myapp/public/stylesheets/style. ss + cria : myapp/views + criar : myapp/views/index. ug + criar : myapp/views/layout.pug + criar : myapp/views/error. ug + create : myapp/bin + create : myapp/bin/www +``` + +Em seguida, instale dependências: + +```bash +$ cd myapp +$ npm install +``` + +No MacOS ou Linux, execute o aplicativo com este comando: + +```bash +$ DEBUG=meuapp:* npm start +``` + +No prompt de comando Windows, use este comando: + +```bash +> definir DEBUG=myapp:* & npm start +``` + +No Windows PowerShell, use este comando: + +```bash +PS> $env:DEBUG='myapp:*'; npm start +``` + +Em seguida, carregue `http://localhost:3000/` no seu navegador para acessar o aplicativo. + +O aplicativo gerado possui a seguinte estrutura de diretórios: + +```bash +. +── app.js +─── bin +├── www +package. son +── public +── imagens +├── javascripts +├── stylesheets +── style styesheets + ─ style. ss +── rotas +├── index.js +─── usuarios +. s +── visões + erros de ── . ug + ── index.pug + ── layout.pug + +diretórios e 9 arquivos +``` + + + +A estrutura do aplicativo criada pelo gerador é apenas uma das muitas maneiras de estruturar aplicativos Express. +Sinta-se livre para usar esta estrutura ou modificá-la para atender às suas necessidades. + + diff --git a/src/content/docs/pt-br/4x/starter/hello-world.mdx b/src/content/docs/pt-br/4x/starter/hello-world.mdx new file mode 100644 index 0000000000..0680e55315 --- /dev/null +++ b/src/content/docs/pt-br/4x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Olá, exemplo do mundo +description: Comece com o Express.js construindo uma simples aplicação 'Hello World'', demonstrando a configuração básica e a criação de servidor para iniciantes. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Embutido abaixo é essencialmente o aplicativo Expresso mais simples que você pode criar. É um único aplicativo de arquivo +— *não* o que você obteria se usar o [Express generator](/en/starter/generator), que +cria o andaime para um aplicativo completo com vários arquivos JavaScript, modelos Jade e subdiretórios +para vários fins. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res. end('Olá Mundo!'); +}); + +app.listen(port, () => { + console.log(`Exemplo app escutando na porta ${port}`); +}); +``` + +Este aplicativo inicia um servidor e escuta na porta 3000 para conexões. O aplicativo responde com "Olá Mundo!" para solicitações +para a URL raiz (`/`) ou *route*. Para todos os outros caminhos, responderá com um **404 Não Encontrado**. + +## Executando localmente + +Primeiro, crie um diretório chamado `myapp`, mude para ele e execute `npm init`. Em seguida, instale `express` como uma dependência, conforme o [guia de instalação](/en/starter/installing). + +No diretório `myapp`, crie um arquivo chamado `app.js` e copie o código do exemplo acima. + + + +O `req` (requisição) e `res` (resposta) são exatamente os mesmos objetos que o Node fornece, para que você possa +invocar `req. ipe()`, `req.on('data', callback)`, e qualquer outra coisa que você faria sem o Express +envolvido. + + + +Execute o aplicativo com o seguinte comando: + +```bash +$ node app.js +``` + +Em seguida, carregue `http://localhost:3000/` em um navegador para ver a saída. diff --git a/src/content/docs/pt-br/4x/starter/installing.mdx b/src/content/docs/pt-br/4x/starter/installing.mdx new file mode 100644 index 0000000000..3f45b5d840 --- /dev/null +++ b/src/content/docs/pt-br/4x/starter/installing.mdx @@ -0,0 +1,49 @@ +--- +title: Instalando +description: Aprenda a instalar o Express.js no seu ambiente Node.js, incluindo a configuração do diretório do seu projeto e o gerenciamento de dependências com npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Antes de começar, certifique-se de ter [Node.js](https://nodejs.org/) 0.10 ou superior instalado. Em seguida, crie um diretório para a sua aplicação e navegue até ele. + +```bash +mkdir myapp +cd myapp +``` + +Use o comando `npm init` para criar um arquivo `package.json` para sua aplicação. +Para obter mais informações sobre como funciona o arquivo `package.json`, veja [Especificações da manipulação do package.json do npm](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +Este comando avisa você para várias coisas, como o nome e a versão de seu aplicativo. +Por enquanto, você simplesmente pode clicar em RETURN para aceitar os padrões para a maioria deles, com a seguinte exceção: + +``` +ponto de entrada: (index.js) +``` + +Digite `app.js`, ou o que quiser que o nome do arquivo principal seja. Se você quer que seja `index.js`, pressione RETURN para aceitar o nome de arquivo padrão sugerido. + +Agora, instale o Express no diretório `myapp` e salve-o na lista de dependências. Por exemplo: + +```bash +Instalação npm expressiva +``` + +Para instalar o Express temporariamente e não adicioná-lo à lista de dependências: + +```bash +npm install express --no-save +``` + + + +Por padrão com a versão npm 5.0+, `npm install` adiciona o módulo à lista de `dependências` no pacote +. arquivo son`; com versões anteriores do npm, você deve especificar a opção `--save`explicitamente. Então, depois, executar`npm install\` no diretório de aplicativos irá automaticamente +instalar módulos na lista de dependências. + + diff --git a/src/content/docs/pt-br/4x/starter/static-files.mdx b/src/content/docs/pt-br/4x/starter/static-files.mdx new file mode 100644 index 0000000000..dcd21f0ab2 --- /dev/null +++ b/src/content/docs/pt-br/4x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Servindo arquivos estáticos no Express +description: Entenda como servir arquivos estáticos como imagens, CSS e JavaScript em aplicativos Express.js usando o middleware "static". +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Para servir arquivos estáticos como imagens, arquivos CSS e arquivos JavaScript, use a função `express.static` middleware embutida no Express. + +A assinatura da função é: + +```js +express.static(root, [options]); +``` + +O argumento `root` especifica o diretório raiz do qual se destinam os assets estáticos. +Para obter mais informações sobre o argumento `options`, consulte [express.static](/en/5x/api#express.static). + +Por exemplo, use o seguinte código para servir imagens, arquivos CSS e arquivos JavaScript em um diretório chamado `public`: + +```js +app.use(express.static('público')); +``` + +Agora, você pode carregar os arquivos que estão no diretório `public`: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Expresso procura os arquivos relativos ao diretório estático, então o nome do diretório estático +não faz parte do URL. + + + +Para usar vários diretórios de ativos estáticos, chame a função `express.static` middleware várias vezes: + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Expresso olha os arquivos na ordem em que você definiu os diretórios estáticos com a função de middleware `express.static`. + + + +Para melhores resultados, use um proxy +reverso cache para melhorar o desempenho do +servindo ativos estáticos. + + + +Para criar um prefixo de caminho virtual (onde o caminho não existe realmente no sistema de arquivos) para arquivos que são servidos pelo `express. função tática`, [especifique um caminho de montagem](/en/5x/api#app.use) para o diretório estático, conforme mostrado abaixo: + +```js +app.use('/static', express.static('public')); +``` + +Agora, você pode carregar os arquivos que estão no diretório `public` a partir do prefixo de caminho `/static`. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +No entanto, o caminho que você fornece para a função `express.static` é relativo ao diretório de onde você inicia seu processo `node`. Se você executar o aplicativo expresso a partir de outro diretório, é mais seguro usar o caminho absoluto do diretório que você deseja servir: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public'))); +``` + +Para mais detalhes sobre a função `serve-static` e suas opções, consulte [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/pt-br/5x/advanced/developing-template-engines.md b/src/content/docs/pt-br/5x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..8b379a6f50 --- /dev/null +++ b/src/content/docs/pt-br/5x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Desenvolvendo modelos de motores para Express +description: Aprenda a desenvolver motores de modelos personalizados para Express.js usando app.engine(), com exemplos sobre como criar e integrar sua própria lógica de renderização de templates. +--- + +Use o método `app.engine(ext, callback)` para criar o seu próprio motor de templates. `ext` refere-se à extensão de arquivo, e `callback` é a função template engine que aceita os seguintes itens como parâmetros: a localização do arquivo, o objeto de opções e a função de retorno de chamada. + +O código a seguir é um exemplo de implementação de um mecanismo muito simples de template para renderizar arquivos `.ntl`. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +Seu aplicativo poderá renderizar arquivos `.ntl`. Crie um arquivo chamado `index.ntl` no diretório `views` com o seguinte conteúdo. + +```pug +#title# +#message# +``` + +Em seguida, crie a seguinte rota no seu app. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +Quando você fizer uma solicitação à página inicial, `index.ntl` será processado como HTML. diff --git a/src/content/docs/pt-br/5x/guide/behind-proxies.mdx b/src/content/docs/pt-br/5x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..1880b62ed0 --- /dev/null +++ b/src/content/docs/pt-br/5x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Expresso atrás dos proxies +description: Aprenda a configurar os aplicativos Express.js para funcionar corretamente atrás de proxies reversas, incluindo o uso do proxy confiável para manipular endereços IP do cliente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Ao executar um app Expresso atrás de um proxy reverso, alguns das APIs Express podem retornar valores diferentes do esperado. A fim de se ajustar para isto, a configuração do aplicativo `trust proxy` pode ser usada para expor informações fornecidas pelo proxy reverso na API Express. O problema mais comum é expressar APIs que expõem o endereço IP do cliente pode mostrar um endereço IP interno do proxy inverso. + + + +Ao configurar a configuração `proxy confiável`, é importante entender a configuração exata do proxy reverso +. Como esta configuração confiará nos valores fornecidos na solicitação, é importante que +a combinação da configuração no Express corresponda a como o proxy reverso funciona. + + + +A configuração do aplicativo 'proxy confiável' pode ser definida para um dos valores listados na tabela a seguir. + + + + + + + + + + + + + + + + + + + + + +
DigiteValor
Boolean +Se `true`, o endereço IP do cliente é entendido como a entrada mais à esquerda no cabeçalho `X-Forwarded-For`. + +Se `false`, o aplicativo é entendido como diretamente virado para o cliente e o endereço IP do cliente é derivado de `req.socket.remoteAddress`. Esta é a configuração padrão. + + +Ao definir como `true`, é importante garantir que o último proxy reverso confiável esteja removendo/substituindo todos os seguintes cabeçalhos HTTP: `X-Forwarded-for`, `X-Forwarded-Host` e `X-Forwarded-Proto`, caso contrário, pode ser possível que o cliente forneça qualquer valor. + +
endereços IP +Um endereço IP, subnet ou uma matriz de endereços IP e subnets para confiar como sendo um proxy reverso. A seguinte lista mostra os nomes das sub-redes pré-configuradas: + +* loopback - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +Você pode definir endereços IP das seguintes maneiras: + +```js +app.set('trust proxy', 'loopback'); // especifica um subnet +app.set('trust proxy', 'loopback, 123.123.123.123'); // especifica um subnet e um aplicativo de endereço +. et('proxy de confiança', 'loopback, linklocal, uniquelocal'); // especificar múltiplas subnets como CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // especificar várias subnets como um array +``` + +Quando especificado, os endereços IP ou as subredes são excluídos do processo de determinação de endereço, e o endereço IP não confiável mais próximo do servidor de aplicativos é definido como o endereço IP do cliente. Isto funciona verificando se 'req.socket.remoteAddress' é confiável. Em caso afirmativo, então cada endereço em `X-Forwarded-For` é verificado da direita para a esquerda até o primeiro endereço não confiável. + +
Número +Use o endereço que, no máximo, está fora do número de hops do aplicativo Express. `req.socket.remoteAddress` é o primeiro hop, e o resto é procurado no cabeçalho `X-Forwarded-for` da direita para a esquerda. Um valor de `0` significa que o primeiro endereço não confiável seria `req.socket.remoteAddress`, ou seja, não há um proxy reverso. + + +Ao usar esta configuração, é importante garantir que não haja vários, caminhos de comprimento diferente para o aplicativo Express, para que o cliente possa ser menor que o número configurado de saltos de distância, caso contrário, poderá ser possível que o cliente forneça qualquer valor. + +
Função +Execução de confiança personalizada. + +```js +app.set('proxy de confiança', (ip) => { + if (ip === '127.0.0.1' ├ip === '123.123.123. 23') + return true; // IPs + else return false; +}); +``` + +
+ +Habilitar `trust proxy` terá o seguinte impacto: + +
    +
  • + O valor de [req.hostname](/en/api#req.hostname) é derivado do valor definido no cabeçalho + `X-Forwarded-Host`, que pode ser configurado pelo cliente ou pelo proxy. +
    • +
  • + `X-Forwarded-Proto` pode ser configurado pelo proxy reverso para dizer ao aplicativo se ele é `https` ou + `http` ou até mesmo um nome inválido. Este valor é refletido por [req.protocol](/en/api#req.protocol). +
    • +
  • + Os valores [req.ip](/en/api#req.ip) e [req.ips](/en/api#req.ips) são preenchidos com base no cabeçalho + do socket e `X-Forwarded-For`, iniciando no primeiro endereço não confiável. +
    • +
+ +A configuração `trust proxy` é implementada usando o pacote [proxy-addr](https://www.npmjs.com/package/proxy-addr). Para obter mais informações, consulte a documentação. diff --git a/src/content/docs/pt-br/5x/guide/debugging.mdx b/src/content/docs/pt-br/5x/guide/debugging.mdx new file mode 100644 index 0000000000..66690a4946 --- /dev/null +++ b/src/content/docs/pt-br/5x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Expresso de depuração +description: Aprenda a habilitar e usar logs de depuração nos aplicativos Express.js definindo a variável de ambiente DEBUG para melhorar a solução de problemas. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Para ver todos os logs internos usados no Express, defina a variável de ambiente `DEBUG` para +`express:*` ao iniciar seu aplicativo. + +```bash +$ DEBUG=express:* node index.js +``` + +No Windows, use o comando correspondente. + +```bash +> $env:DEBUG = "express:*"; node index.js +``` + +Executar este comando no aplicativo padrão gerado pelo [gerador expresso](/en/starter/generator) imprime a seguinte saída: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +Quando um pedido for feito ao aplicativo, você verá os logs especificados no código Expresso: + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index.pug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +Para ver os logs apenas da implementação do roteador, defina o valor de `DEBUG` para `express:router`. Da mesma forma, para ver apenas os logs da implementação do aplicativo, defina o valor de `DEBUG` para `express:application`, e assim por diante. + +## Aplicações geradas por `express` + +Uma aplicação gerada pelo comando `express` usa o módulo `debug` e seu namespace de depuração é escopo para o nome da aplicação. + +Por exemplo, se você gerou o app com `$ express sample-app`, você pode ativar as instruções de depuração com o seguinte comando: + +```bash +$ DEBUG=sample-app:* node ./bin/www +``` + +Você pode especificar mais de um namespace de depuração atribuindo uma lista de nomes separada por vírgulas: + +```bash +$ DEBUG=http,mail,express:* node index.js +``` + +## Opções avançadas + +Ao executar através do Node.js, você pode definir algumas variáveis de ambiente que irão mudar o comportamento do log de depuração: + +| Nome: | Objetivo | +| ------------------- | -------------------------------------------------------- | +| `DEBUG` | Habilita/desabilita namespace específicos de depuração. | +| `DEBUG_COLORS` | Usar ou não cores na saída de depuração. | +| DEBUG_DEPTH\` | Profundidade da inspeção de objeto. | +| `DEBUG_FD` | Descritor de arquivo para escrever a saída de depuração. | +| `DEBUG_SHOW_HIDDEN` | Mostra propriedades ocultas em objetos inspecionados. | + + + +As variáveis de ambiente começando com `DEBUG_` acabam sendo convertidas em um objeto de Opções +que é usado com formatos `%o`/`%O`. Veja a documentação do Node.js sobre +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) para a lista +completa. + + diff --git a/src/content/docs/pt-br/5x/guide/error-handling.mdx b/src/content/docs/pt-br/5x/guide/error-handling.mdx new file mode 100644 index 0000000000..c0d1aa28c7 --- /dev/null +++ b/src/content/docs/pt-br/5x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Tratamento de erros +description: Entenda como o Express.js lida com erros em código síncrono e assíncrono e aprenda a implementar erro personalizado de manipulação de intermediários para seus aplicativos. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Tratamento de erros* refere-se a como as capturas Expressas e processa erros que +ocorrem de forma sincronizada e assíncrona. Expresso vem com um erro padrão +manipulador para que você não precise escrever seu próprio para começar. + +## Capturando Erros + +É importante garantir que Expresso pegue todos os erros que ocorrem enquanto +rodando manipuladores de rotas e intermediários. + +Erros que ocorrem no código síncrono dentro dos manipuladores de rota e middleware +não exigem trabalho extra. If synchronous code throws an error, then Express will +catch and process it. Por exemplo: + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Expresso irá pegar isso sozinho. +}); +``` + +Para erros retornados de funções assíncronas, invocados pelos manipuladores de rota +e intermediário, você deve passá-los para a função `next()`, onde o Express irá capturá-los a +e processá-los. Por exemplo: + +```js +app.get('/', (req, res, next) => { + fs. eadFile('/file-does-not-existente', (err, data) => { + if (err) { + next(err); // Passa os erros para o Express. + } else { + res. end(data); + } + }); +}); +``` + +Começando pelo Express 5, roteadores e intermediários que retornam um Promise +chamarão `next(value)` automaticamente quando eles rejeitarem ou lançarem um erro. +Por exemplo: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = await getUserById(req.params.id); + res.send(user); +}); +``` + +Se `getUserById` lança um erro ou rejeita, `next` será chamado com +o erro lançado ou o valor rejeitado. Se nenhum valor rejeitado for fornecido, `next` +será chamado com um objeto de erro padrão fornecido pelo roteador Express. + +Se você passar qualquer coisa para a função `next()` (exceto a string `'route'`), +Expressa que a requisição atual é um erro e irá pular quaisquer funções +restantes que não sejam de manipulação de erros e middleware. + +Se o callback em uma sequência não fornecer dados, somente erros, você pode simplificar +este código da seguinte forma: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +No exemplo acima, `next` é fornecido como o callback para `fs.writeFile`, +que é chamado com ou sem erros. Se não houver erro, o segundo receptor +é executado, caso contrário as pegadas do Express e processa o erro. + +Você deve capturar os erros que ocorrem em código assíncrono invocado pelos manipuladores da rota ou +middleware e passá-los para o Expresso para processamento. Por exemplo: + +```js +app.get('/', (q, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + ext(err); + } + }, 100); +}); +``` + +O exemplo acima usa um bloco `tentar... catch` para capturar erros no código assíncrono +e passá-los para o Express. Se o bloco `tentar...catch` +fosse omitido, Express não pegaria o erro, uma vez que ele não faz parte do código de manipulador +síncrono. + +Use promessas para evitar a sobrecarga do bloco `tentar... capturar` ou ao usar funções +que retornam promessas. Por exemplo: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + . hen(() => { + joga novo Error('BROKEN'); + }) + . atch(next); // Erros serão passados para o Express. +}); +``` + +Since promises automatically catch both synchronous errors and rejected promises, +you can simply provide `next` as the final catch handler and Express will catch errors, +because the catch handler is given the error as the first argument. + +Você também pode usar uma cadeia de manipuladores para confiar em erro síncrono +de recuperação, reduzindo o código assíncrono a algo trivial. Por exemplo: + +```js +app.get('/', [ + função (req, res, ext) { + fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals. ata = data; + ext(err); + }); + }, + função (req, res) { + res. ocals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +O exemplo acima tem algumas declarações triviais da chamada `readFile` +. If `readFile` causes an error, then it passes the error to Express, otherwise you +quickly return to the world of synchronous error handling in the next handler +in the chain. Então, o exemplo acima tenta processar os dados. Se isso falhar, o manipulador de erro +síncrono irá pegá-lo. Se você tivesse feito este processamento dentro do +o callback `readFile`, então o aplicativo poderia sair e o erro Express +manipuladores não executariam. + +Seja qual for o método que você usar, se você quer que os manipuladores de erro Expressos sejam chamados para dentro e o aplicativo +para sobreviver, você deve garantir que o Expresso receba o erro. + +## O manipulador de erro padrão + +Expresso vem com um manipulador de erro embutido que cuida de quaisquer erros que possam ser encontrados no aplicativo. Esta função de middleware com erros padrão é adicionada no final da função middleware stack. + +Se você passar um erro para `next()` e não lidar com ele em um erro personalizado +handler, será tratado pelo manipulador de erro embutido; o erro será +escrito no cliente com o rastreamento de pilha. O rastreamento da pilha não está incluído +no ambiente de produção. + + + +Defina a variável de ambiente `NODE_ENV` como `production`, para executar o aplicativo em modo de produção. + + + +Quando um erro é escrito, a seguinte informação é adicionada a +resposta: + +* O `res.statusCode` é definido em `err.status` (ou `err.statusCode`). Se + este valor estiver fora do intervalo de 4xx ou 5xx, ele será definido como 500. +* A mensagem 'res.statusMessage' é definida de acordo com o código de status. +* O corpo será o HTML da mensagem do código de status quando em produção + ambiente, caso contrário será `err.stack`. +* Qualquer cabeçalho especificado em um objeto `err.headers`. + +Se você chamar `next()` com um erro depois que você começou a escrever a +resposta (por exemplo, se você encontrar um erro ao transmitir a resposta +ao cliente), o Express default error handler fecha a conexão +e falha na solicitação. + +Então, quando você adicionar um manipulador de erro personalizado, você deve delegar para +o manipulador de erro padrão Express, quando os cabeçalhos +já foram enviados para o cliente: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Observe que o manipulador de erro padrão pode ser acionado se você chamar `next()` com um erro +no seu código mais de uma vez. Mesmo que um erro personalizado de manipulação de middleware esteja no lugar. + +Outro erro de manipulação de middleware pode ser encontrado em [Express middleware](/en/resources/middleware). + +## Escrevendo manipuladores de erros + +Definir funções intermediárias de manipulação de erros da mesma forma que outras funções de middleware, +exceto funções de manipulação de erro possuem quatro argumentos ao invés de três: +`(err, req, res, next)`. Por exemplo: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Algo quebrado!'); +}); +``` + +Você define o middleware de erro duramente, depois de outro `app.use()` e roteia chamadas; por exemplo: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser. rlencoded({ + extendido: true, + }) +); +app.use(bodyParser.json()); +app. se(methodOverride()); +app.use((err, req, res, next) => { + // lógica +}); +``` + +As respostas de dentro de uma função middleware podem estar em qualquer formato, como uma página de erro HTML, uma mensagem simples ou uma string JSON. + +Para fins de estrutura organizacional (e de nível superior), você pode definir +várias funções de middleware com manipulação de erros, tanto quanto você poderia com funções de intermediário +regulares. Por exemplo, para definir um manipulador de erro +para solicitações feitas usando `XHR` e aqueles sem: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app. se( + bodyParser.urlencoded({ + extendido: true, + }) +); +app. se(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +In this example, the generic `logErrors` might write request and +error information to `stderr`, for example: + +```js +function logErrors(err, req, res, ext) { + console.error(err.stack); + next(err); +} +``` + +Também neste exemplo, `clientErrorHandler` é definido como segue; neste caso, o erro é explicitamente passado para o próximo. + +Observe que quando *não* estiver chamando "próximo" em uma função de manipulação de erros, você é responsável por escrever (e terminar) a resposta. Caso contrário, esses pedidos ficarão "pendentes" e não serão elegíveis para a recolha de lixo. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500). end({ error: 'Algo falhou!' }); + } else { + next(err); + } +} +``` + +Implementar a função "catch-all" `errorHandler` da seguinte forma (por exemplo): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +Se você tiver um gerenciador de rotas com múltiplas funções de retorno de chamada, você pode usar o parâmetro `rota` para pular para o próximo manipulador de rota. Por exemplo: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user. asPaid) { + // continue lidando com esta requisição + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent. ind((err, doc) => { + se (err) retornar next(err); + res. son(doc); + }); + } +); +``` + +Neste exemplo, o manipulador `getPaidContent` será ignorado, mas quaisquer manipuladores restantes em `app` para `/a_route_behind_paywall` continuariam sendo executados. + + + +Chama para `next()` e `next(err)` indicam que o manipulador atual está completo e em que estado. +`next(err)` pulará todos os manipuladores restantes na cadeia, exceto aqueles que estão configurados para +lidar com erros conforme descrito acima. + + diff --git a/src/content/docs/pt-br/5x/guide/overriding-express-api.md b/src/content/docs/pt-br/5x/guide/overriding-express-api.md new file mode 100644 index 0000000000..d5ceef01af --- /dev/null +++ b/src/content/docs/pt-br/5x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Sobrescrevendo a API Expresso +description: Descubra como personalizar e estender a API do Express.js substituindo métodos e propriedades nos objetos de solicitação e resposta usando protótipos. +--- + +A API do Expresso consiste de vários métodos e propriedades nos objetos de solicitação e resposta. Estas são herdadas pelo protótipo. Há dois pontos de extensão para a API Express: + +1. Os protótipos globais em `express.request` e `express.response`. +2. Protótipos específicos de aplicativo em `app.request` e `app.response`. + +Alterar os protótipos globais afetará todos os aplicativos do Express carregados no mesmo processo. Se desejar, alterações podem ser feitas especificamente no aplicativo, alterando apenas os protótipos específicos do aplicativo após criar um novo aplicativo. + +## Métodos + +Você pode substituir a assinatura e o comportamento dos métodos existentes com o seu próprio, atribuindo uma função personalizada. + +A seguir é um exemplo de substituição do comportamento de [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +A implementação acima altera completamente a assinatura original de `res.sendStatus`. Agora aceita um código de estado, um tipo de codificação e a mensagem a ser enviada ao cliente. + +O método sobrescrito agora pode ser usado dessa maneira: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## propriedades + +As propriedades da API Expresso também são: + +1. Propriedades atribuídas (ex: `req.baseUrl`, `req.originalUrl`) +2. Definido como getters (ex: `req.secure`, `req.ip`) + +Uma vez que as propriedades da categoria 1 são dinamicamente atribuídas aos objetos `request` e `response` no contexto do ciclo atual de resposta de solicitação, seu comportamento não pode ser substituído. + +As propriedades da categoria 2 podem ser substituídas usando a API de extensões de API Express. + +O código a seguir reescreve como o valor de `req.ip` deve ser derivado. Agora, ele simplesmente retorna o valor do cabeçalho de solicitação `Client-IP`. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Protótipo + +Para fornecer a API Express, os objetos de solicitação/resposta passados para Express (via `app(req, res)`, por exemplo) precisam herdar do mesmo tipo de cadeia. Por padrão, isto é `http.IncomingRequest.prototype` para a solicitação e `http.ServerResponse.prototype` para a resposta. + +Se necessário, recomenda-se que isso seja feito apenas a nível da aplicação, e não a nível global. Além disso, tenha cuidado para que o protótipo usado corresponda à funcionalidade o mais próximo possível dos protótipos padrão. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/pt-br/5x/guide/routing.mdx b/src/content/docs/pt-br/5x/guide/routing.mdx new file mode 100644 index 0000000000..c8e9e2d7a3 --- /dev/null +++ b/src/content/docs/pt-br/5x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Roteamento +description: Aprenda a definir e usar rotas em aplicações Express.js, incluindo métodos de rota, caminhos de rota, parâmetros e usando o roteador para roteamento modular. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* refere-se a como os endpoints de um aplicativo (URIs) respondem às solicitações do cliente. +Para uma introdução ao roteamento, veja [Roteamento básico](/en/starter/basic-routing). + +Você define roteamento usando métodos do objeto Express `app` que correspondem aos métodos HTTP; +por exemplo, `app. et()` para lidar com solicitações GET e `app.post` para lidar com solicitações POST. Para obter uma lista completa, +ver [app.METHOD](/en/5x/api#app.METHOD). Você também pode usar o [app.all()](/en/5x/api#app.all) para lidar com todos os métodos HTTP e [app. se()](/en/5x/api#app.use) para +especifique middleware como função de retorno de chamada (Veja [Usando middleware](/en/guide/using-middleware) para detalhes). + +Esses métodos de roteamento especificam uma função de callback (às vezes chamada de "funções de manipulador") chamada quando a aplicação recebe uma solicitação para a rota especificada (endpoint) e método HTTP. Em outras palavras, o aplicativo "listas" para solicitações que correspondem com a(s) rota(s) e método(s) especificado(s), e quando ela detecta uma correspondência, ela chama a função de retorno de chamada especificado. + +Na verdade, os métodos de roteamento podem ter mais de uma função de callback como argumentos. +Com múltiplas funções de callback, é importante fornecer `next` como um argumento para a função de callback e então chamar `next()` dentro do corpo da função para liberar o controle +para a próxima callback. + +O código a seguir é um exemplo de uma rota muito básica. + +```js +const express = require('express'); +const app = express(); + +// responda com "olá mundo" quando for feita uma solicitação GET para a página inicial +app. et('/', (req, res) => { + res.send('hello world'); +}); +``` + +## Métodos de rota + +Um método de route é derivado de um dos métodos HTTP e é anexado a uma instância da classe 'express'. + +O código a seguir é um exemplo de rotas que são definidas para os métodos `GET` e `POST` para a raiz do aplicativo. + +```js +// GET method route +app.get('/', (req, res) => { + res.send('GET request to the homepage'); +}); + +// POST method route +app.post('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Expresso suporta métodos que correspondem a todos os métodos de requisição HTTP: `get`, `post`, e assim por diante. +Para uma lista completa, consulte [app.METHOD](/en/5x/api#app.METHOD). + +Há um método de roteamento especial, `app.all()`, usado para carregar funções de middleware em um caminho para os métodos de requisição HTTP. Por exemplo, o seguinte manipulador é executado para solicitações para a rota `"/secre"` usando `GET`, `POST`, `PUT`, `DELETE`, ou qualquer outro método de solicitação HTTP suportado no [módulo http](https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Acessando a seção secreta ...'); + next(); // passe o controle para o próximo manipulador +}); +``` + +## Caminho da rota + +Roteamento, em combinação com um método de solicitação, defina os pontos de extremidade em que as solicitações podem ser feitas. Caminhos de rota podem ser frases, padrões de strings ou expressões regulares. + + + +Expresso 5, os caracteres `? , `+`, `\*`, `[]`, e `()\` são tratados de forma diferente da versão +4, por favor, revise o [guia de migração](/en/guide/migrating-5#path-syntax) para mais informações. + + + + + +No modo expresso 4, caracteres de expressão regular como `$` precisam ser escapados com um `\`. + + + + + +Expresso usa [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) para corresponder à rota +caminhos; veja a documentação pay-to-regexp para todas as possibilidades em definir caminhos da rota. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) é uma ferramenta útil para +testar rotas Express, embora não suporte correspondência de padrões. + + + +strings de consulta não fazem parte do caminho de rota. + +### Caminhos de rota baseados em strings + +Este caminho de rota irá corresponder a solicitações para a rota raiz, `/`. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +Esse caminho de rota irá corresponder a solicitações para `/about`. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +Este caminho de rota irá corresponder a solicitações para `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Caminhos de rota baseados em padrões string + + + +Os padrões de string no Express 5 não funcionam mais. Por favor, consulte o [guia de migração +] (/en/guide/migrating-5#path-syntax) para obter mais informações. + + + +Este caminho de rota corresponderá a 'acd' e 'abcd'. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +Esse caminho de rota corresponderá a `abcd`, `abbcd`, `abbbcd`, e assim por diante. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +Esse caminho de rota irá coincidir com `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd`, e assim por diante. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +Esta rota de rota irá corresponder a `/abe` e `/abcde`. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Caminho baseado em expressões regulares + +Este caminho de rota combinará com qualquer coisa com "a" nele. + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +Esse caminho de rota irá coincidir com `borboleta` e `dragonfly`, mas não com `borboleta`, `dragonflyman`, e assim por diante. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Parâmetros de rota + +Parâmetros de rota são denominados segmentos de URL que são usados para capturar os valores especificados em sua posição na URL. Os valores capturados são preenchidos no objeto `req.params`, com o nome do parâmetro de rota especificado no caminho como suas respectivas chaves. + +``` +Caminho da rota: /users/:userId/books/:bookId +Solicitação URL: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +Para definir rotas com parâmetros de rota, simplesmente especifique os parâmetros de rota no caminho da rota, conforme mostrado abaixo. + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +O nome dos parâmetros de rota deve ser composto de "palavra caracteres" ([A-Za-z0-9_]). + + + +Como o hífen (`-`) e o ponto (`.`) são interpretados literalmente, eles podem ser usados juntamente com parâmetros de rota para fins úteis. + +``` +Caminho da rota: /fvots/:from-:to +Solicitação URL: http://localhost:3000/fvots/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Caminho da rota: /plantae/:genus.:species +Solicitação URL: http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "espécies": "persica" } +``` + + + +Expresso 5, Regexp caracteres não são suportados nos caminhos de rota, para mais informações por favor +consulte o [guia de migração](/en/guide/migrating-5#path-syntax). + + + +Para ter mais controle sobre a string exata que pode ser combinada por um parâmetro de rota, você pode acrescentar uma expressão regular entre parênteses (`()`): + +``` +Caminho da rota: /user/:userId(\d+) +Solicitar URL: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Porque a expressão regular geralmente faz parte de uma cadeia literal, certifique-se de escapar de quaisquer caracteres `\` +com uma barra invertida adicional, por exemplo `\d+`. + + + + +No Expresso 4.x, o caractere `*` em expressões regulares não é interpretado da maneira habitual. Como uma alternativa, use `{0,}` em vez de `*`. Isso provavelmente será corrigido no Express 5. + + +## Manipuladores de rota + +Você pode fornecer várias funções de retorno de chamada que se comportam como [middleware](/en/guide/using-middleware) para lidar com uma solicitação. A única exceção é que esses callbacks podem invocar `next('route')` para ignorar as chamadas restantes da rota. Você pode usar este mecanismo para impor pré-condições em uma rota, então passe controle para rotas subsequentes se não houver motivo para prosseguir com a rota atual. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params. d === '0') { + return next('rota'); + } + res. end(`Usuário ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('ID especial para o ID de usuário 0'); +}); +``` + +Neste exemplo: + +* `GET /user/5` → tratado pela primeira rota → envia "Usuário 5" +* `GET /user/0` → primeira rota chama `next('rote')`, pulando para a próxima rota `/user/:id` correspondente + +Os manipuladores de rotas podem estar na forma de uma função, um array de funções ou combinações de ambos, como mostrado nos exemplos a seguir. + +Uma única função de retorno de chamada pode manipular uma rota. Por exemplo: + +```js +app.get('/example/a', (req, res) => { + res.send('Olá de A!'); +}); +``` + +Mais de uma função de retorno de chamada pode manipular uma rota (certifique-se de especificar o objeto `next`). Por exemplo: + +```js +app.get( + '/example/b', + (req, res, next) => { + console. og('a resposta será enviada pela próxima função. .'); + next(); + }, + (req, res) => { + res. end('Olá de B!'); + } +); +``` + +Um array de funções de retorno de chamada pode lidar com uma rota. Por exemplo: + +```js +const cb0 = function (req, res, next) { + console. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +const cb2 = function (req, res) { + res. end('Olá de C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +Uma combinação de funções independentes e matrizes de funções pode lidar com uma rota. Por exemplo: + +```js +const cb0 = function (req, res, next) { + console. og('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console. og('CB1'); + next(); +}; + +aplicativo. et( + '/example/d', + [cb0, cb1], + (req, res, next) => { + console. og('a resposta será enviada pela próxima função. .'); + next(); + }, + (req, res) => { + res. end('Olá de D!'); + } +); +``` + +## Métodos de resposta + +Os métodos no objeto de resposta ('res') na tabela a seguir podem enviar uma resposta para o cliente e encerrar o ciclo de resposta de solicitação. Se nenhum destes métodos for chamado de um manipulador de redes, a solicitação do cliente será deixada em suspenso. + +| Método | Descrição: | +| --------------------------------------------- | --------------------------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | Solicite que um arquivo seja baixado. | +| [res.end()](/en/5x/api#res.end) | Encerrar o processo de resposta. | +| [res.json()](/en/5x/api#res.json) | Enviar uma resposta JSON. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Envie uma resposta JSON com suporte a JSONP. | +| [res.redirect()](/en/5x/api#res.redirect) | Redirecionar uma requisição. | +| [res.render()](/en/5x/api#res.render) | Renderizar um modelo de visão. | +| [res.send()](/en/5x/api#res.send) | Envie uma resposta de vários tipos. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Envia um arquivo como uma transmissão octet. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Defina o código de status da resposta e envie sua representação de string como o corpo da resposta. | + +## app.route() + +Você pode criar manipuladores de rotas em cadeia para um caminho de rota usando `app.route()`. +Como o caminho é especificado em um único local, é útil criar rotas modulares, assim como reduzir a redundância e os tipos. Para obter mais informações sobre rotas, consulte: [documentação de roteador](/en/5x/api#router). + +Aqui está um exemplo de manipuladores de rota encadeados que são definidos usando `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res. end('Recebe um livro aleatório'); + }) + . ost((req, res) => { + res.send('Adicionar um livro'); + }) + . ut((req, res) => { + res.send('Atualizar o livro'); +}); +``` + +## expressão.Roteador + +Use a classe 'express.Router' para criar módulo, manipuladores de rotas montáveis. Uma instância `Router` é um sistema completo de middleware e roteamento; por este motivo, é muitas vezes referido como um "mini-app". + +O exemplo a seguir cria um roteador como um módulo, carrega uma função middleware nele define algumas rotas e monta o módulo do roteador em um caminho no aplicativo principal. + +Crie um arquivo de roteador chamado `birds.js` no diretório de aplicativos, com o seguinte conteúdo: + +```js +const express = require('express'); +const router = express.Router(); + +// middleware that is specific to this router +const timeLog = (req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}; +router.use(timeLog); + +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Em seguida, carregue o módulo do roteador no aplicativo: + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +O aplicativo agora poderá lidar com pedidos para `/birds` e `/birds/about`, Além de chamar a função middleware `timeLog` que é específica da rota. + +Mas se a rota pai `/birds` tiver parâmetros de caminho, ela não será acessível por padrão nas sub-rotas. Para torná-lo acessível, você precisará passar a opção `mergeParams` para o construtor do roteador [reference](/en/5x/api#app.use). + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/pt-br/5x/guide/using-middleware.mdx b/src/content/docs/pt-br/5x/guide/using-middleware.mdx new file mode 100644 index 0000000000..c1e4bab642 --- /dev/null +++ b/src/content/docs/pt-br/5x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Usando o middleware +description: Aprenda a usar o middleware em aplicativos do Express.js, incluindo o nível de aplicativos e o middleware, manipulação de erros e integração de intermediários de terceiros. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express é uma web framework de roteamento e middleware que tem a funcionalidade mínima de sua própria funcionalidade: Um aplicativo Express é essencialmente uma série de chamadas de função middleware. + +Middleware_ são funções que têm acesso ao [objeto de requisição](/en/5x/api#req) (`req`), a [objeto de resposta](/en/5x/api#res) (`res`) e a próxima função de middleware no ciclo de resposta de solicitação do aplicativo. A próxima função de middleware é comumente denotada por uma variável chamada `next`. + +As funções do Middleware podem executar as seguintes tarefas: + +* Execute qualquer código. +* Fazer alterações na solicitação e nos objetos de resposta. +* Encerrar o ciclo de solicitação-resposta. +* Chame a próxima função middleware na pilha. + +Se a função middleware atual não encerra o ciclo de resposta de solicitação, ela deve chamar `next()` para passar o controle para a próxima função middleware. Caso contrário, o pedido ficará pendurado. + +Um aplicativo Express pode usar os seguintes tipos de middleware: + +* [Meio do aplicativo](#middleware.application) +* [Meio do roteador](#middleware.router) +* [Middleware com erro](#middleware.error-handling) +* [middleware](#middleware.built-in) +* [Middleware de terceiros](#middleware.third-party) + +Você pode carregar o nível de aplicação e middleware de nível de roteador com um caminho de montagem opcional. +Você também pode carregar uma série de funções intermediárias juntas, o que cria uma sub-pilha do sistema intermediário em um ponto de montagem. + +## Midddleware no nível de aplicação + +Vincular aplicativo de nível middleware a uma instância do [objeto de aplicativo](/en/5x/api#app) usando o `app.use()` e `app. Funções ETHOD()`, onde `METHOD` é o método HTTP da solicitação que a função middleware lida (como GET, PUT, ou POST) em minúsculas. + +Este exemplo mostra uma função middleware sem caminho de montagem. A função é executada toda vez que o aplicativo recebe uma solicitação. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +Este exemplo mostra uma função middleware montada no caminho `/user/:id`. A função é executada para qualquer tipo de solicitação HTTP +no caminho `/user/:id`. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Tipo de requisição:', req.method); + next(); +}); +``` + +Este exemplo mostra uma rota e sua função de manipulador (sistema de middleware). A função lida com requisições GET para o caminho `/user/:id`. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +Aqui está um exemplo de carregar uma série de funções intermediárias em um ponto de montagem, com um caminho de montagem. +Isto ilustra um sub-stack de middleware que imprime informação de solicitação para qualquer tipo de solicitação de HTTP no caminho `/user/:id`. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Solicitação de URL:', req. riginalUrl); + next(); + }, + (req, res, next) => console { + . og('Tipo de requisição:', req.method); + next(); + } + +``` + +Os gerenciadores de rotas permitem que você defina várias rotas para um caminho. O exemplo abaixo define duas rotas para solicitações GET para o caminho `/user/:id`. A segunda via não causará quaisquer problemas, mas nunca será chamada, porque a primeira via termina o ciclo de resposta aos pedidos. + +Este exemplo mostra uma sub-pilha de middleware que lida com requisições GET para o caminho `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req. arams.id); + next(); + }, + (req, res, next) => { + res. end('Informações do usuário'); + } +); + +// manipulador para o caminho /user/:id, que imprime o ID do usuário +aplicativo. et('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +Para ignorar o resto das funções de middleware a partir de uma pilha de middleware do roteador, chame `next('route')` para passar o controle para a próxima rota. + + + +`next('rota')` funcionará apenas em funções de middleware que foram carregadas usando as funções +`app.METHOD()` ou `router.METHOD()`. + + + +Este exemplo mostra uma sub-pilha de middleware que lida com requisições GET para o caminho `/user/:id`. + +```js +app.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next route + if (req.params.id === '0') next('route'); + // otherwise pass the control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // send a regular response + res.send('regular'); + } +); + +// handler for the /user/:id path, which sends a special response +app.get('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +O Middleware também pode ser declarado em um array para reutilizabilidade. + +Este exemplo mostra um array com um sub-stack de middleware que lida com requisições GET para o caminho `/user/:id` + +```js +function logOriginalUrl(req, res, próximo) { + console.log('Solicitação URL:', req. riginalUrl); + next(); +} + +function logMethod(req, res, ext) { + console.log('Request Type:', req. ethod); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app. et('/user/:id', logStuff, (req, res, next) => { + res.send('Usuário Info'); +}); +``` + +## Midddleware nível de roteamento + +O middleware de roteador funciona da mesma maneira que o middleware no nível de aplicativo, exceto que está vinculado a uma instância de `express.Router()`. + +```js +const router = express.Router(); +``` + +Carregue o middleware no nível de roteador usando as funções `router.use()` e `router.METHOD()`. + +O código a seguir replica o sistema middleware que é mostrado acima para o middleware no nível de aplicativos, usando o middleware no nível de roteador: + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// a middleware function with no mount path. This code is executed for every request to the router +router.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); + +// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path +router.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); + +// a middleware sub-stack that handles GET requests to the /user/:id path +router.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next router + if (req.params.id === '0') next('route'); + // otherwise pass control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // render a regular page + res.render('regular'); + } +); + +// handler for the /user/:id path, which renders a special page +router.get('/user/:id', (req, res, next) => { + console.log(req.params.id); + res.render('special'); +}); + +// mount the router on the app +app.use('/', router); +``` + +Para ignorar o resto das funções de middleware do roteador, chame `next('router')` +para passar o controle de volta para fora da instância do roteador. + +Este exemplo mostra uma sub-pilha de middleware que lida com requisições GET para o caminho `/user/:id`. + +```js +const express = require('express'); +const app = express(); +const router = expressos. + +// prefixa o roteador com uma verificação e resgate quando necessário +roteador. se((req, res, ext) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router. et('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// usa o roteador e 401 tudo que cai através do app +. se('/admin', roteador, (req, res) => { + res.sendStatus(401); +}); +``` + +## Midddleware com erro manipulado + + + +O middleware com erros de manipulação sempre toma *quatro* argumentos. Você deve fornecer quatro argumentos para +identificá-lo como uma função de middleware manipulação de erros. Mesmo se você não precisar usar o objeto `next` +, você deve especificá-lo para manter a assinatura. Caso contrário, o objeto `próximo` será +interpretado como um middleware regular e irá falhar em lidar com erros. + + + +Definir funções intermediárias de manipulação de erros da mesma forma que outras funções de middleware, exceto quatro argumentos em vez de três, especificamente com a assinatura `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Algo quebrado!'); +}); +``` + +Para detalhes sobre o middleware, consulte: [Error handling](/en/guide/error-handling). + +## Midddleware integrado + +A partir da versão 4.x, o Express não depende mais do [Connect](https://github.com/senchalabs/connect). O middleware +funções que foram previamente incluídas com Express estão agora em módulos separados; consulte [a lista de funções de middleware](https://github.com/senchalabs/connect#middleware). + +O Express tem as seguintes funções de middleware incorporadas: + +* [express.static](/en/5x/api#express.static) serve como arquivos estáticos, como arquivos HTML, imagens e assim por diante. +* [express.json](/en/5x/api#express.json) analisa solicitações recebidas com carga JSON. **NOTA: Disponível com Expresso 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) analisa solicitações recebidas com payloads codificados por URL. **NOTA: Disponível com Expresso 4.16.0+** + +## Midddleware de terceiros + +Usar middleware de terceiros para adicionar funcionalidades a aplicativos Express. + +Instale o módulo Node.js para a funcionalidade requerida e, em seguida, carregue-o em seu aplicativo ao nível do aplicativo ou no nível do roteador. + +O exemplo a seguir ilustra a instalação e o carregamento da função middleware de análise de cookie-parser\`. + +```bash +$ npm install cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// carrega o middleware +app.use(cookieParser()); +``` + +Para uma lista parcial de funções intermediárias de terceiros que são comumente usadas com Express, veja: [middleware de terceiros](../resources/middleware). diff --git a/src/content/docs/pt-br/5x/guide/using-template-engines.mdx b/src/content/docs/pt-br/5x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..ff8b9c8e16 --- /dev/null +++ b/src/content/docs/pt-br/5x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Usando mecanismos de template com o Express +description: Descubra como integrar e usar mecanismos de modelos como Pug, Handlebars, e EJS com Express.js para renderizar páginas HTML dinâmicas de forma eficiente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Um *motor de template* permite que você use arquivos de template estáticos na sua aplicação. At runtime, the template engine replaces +variables in a template file with actual values, and transforms the template into an HTML file sent to the client. +Esta abordagem torna mais fácil projetar uma página HTML. + +O [gerador de aplicação Expressa](/en/starter/generator) usa [Pug](https://pugjs.org/api/getting-started.html) como seu padrão, mas também apoia [Handlebars](https://www.npmjs.com/package/handlebars), e [EJS](https://www.npmjs.com/package/ejs), entre outros. + +Para renderizar arquivos de template, defina as seguintes [propriedades de configuração da aplicação](/en/4x/api#app.set), no `app.js` padrão criado pelo gerador: + +* `views`, o diretório onde se localizam os arquivos de template. Ex: `app.set('views', './views')`. + Isto é padrão para o diretório `views` no diretório raiz do aplicativo. +* `ver engenho`, o mecanismo de modelos a ser usado. Por exemplo, para usar o motor de template Pug: `app.set('engenharia de visualização', 'pug')`. + +Então instale o correspondente mecanismo de template do npm pacote; por exemplo, para instalar o Pug: + +```bash +$ npm install pug --save +``` + + +Mecanismos de template compatíveis com o código, como Pug exporta uma função chamada `__express(filePath, opções, callback)`, +que `res.render()` chama para renderizar o código de template. + +Alguns motores de modelos não seguem esta convenção. A biblioteca [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +segue esta convenção mapeando todos os mecanismos de modelo populares de Node.js e, portanto, funciona perfeitamente dentro do Express. + + + +Depois que o motor de visualização estiver definido, você não precisa especificar o motor ou carregar o módulo de mecanismo de modelo no seu aplicativo; +Expresso carrega o módulo internamente, por exemplo: + +```js +app.set('mecanismo de visão', 'pug'); +``` + +Em seguida, crie um arquivo de template Pug chamado `index.pug` no diretório `views`, com o seguinte conteúdo: + +```pug +html + head + title= title + corpo + h1= mensagem +``` + +Crie uma rota para renderizar o arquivo `index.pug`. Se a propriedade `view engine` não estiver definida, +você deve especificar a extensão do arquivo `view`. Caso contrário, você pode omitir. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Ei', message: 'Olá lá!' }); +}); +``` + +Quando você faz uma solicitação à página inicial, o arquivo `index.pug` será processado como HTML. + +O cache do motor de exibição não armazena o conteúdo da saída do modelo, apenas o modelo subjacente em si. A visualização ainda é renderizada novamente com todas as requisições, mesmo que o cache esteja ativo. diff --git a/src/content/docs/pt-br/5x/guide/writing-middleware.mdx b/src/content/docs/pt-br/5x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..1eefc7c736 --- /dev/null +++ b/src/content/docs/pt-br/5x/guide/writing-middleware.mdx @@ -0,0 +1,209 @@ +--- +title: Escrever middleware para uso nos aplicativos Express +description: Aprenda a escrever funções de middleware personalizadas para aplicativos Express.js, incluindo exemplos e melhores práticas para melhorar a resolução de pedidos e respostas. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Middleware_ são funções que têm acesso ao [objeto de requisição](/en/5x/api#req) (`req`), a [objeto de resposta](/en/5x/api#res) (`res`) e a função `next` no ciclo de resposta de solicitação do aplicativo. A função `próxima` é uma função no roteador Expresso que, quando invocado, executa o intermediário sucedendo ao intermediário atual. + +As funções do Middleware podem executar as seguintes tarefas: + +* Execute qualquer código. +* Fazer alterações na solicitação e nos objetos de resposta. +* Encerrar o ciclo de solicitação-resposta. +* Chame o próximo middleware na pilha. + +Se a função middleware atual não encerra o ciclo de resposta de solicitação, ela deve chamar `next()` para passar o controle para a próxima função middleware. Caso contrário, o pedido ficará pendurado. + +A figura a seguir mostra os elementos de uma chamada de função middleware: + +![Elementos de uma chamada de função middleware](/images/express-mw.png) + +Começando com as funções de middleware Express, funções de intermediário que retornam uma Promessa chamarão `próximo(valor)` quando eles rejeitarem ou lançarem um erro. `next` será chamado com o valor rejeitado ou o erro lançado. + +## Exemplo + +Aqui está um exemplo de uma aplicação simples "Hello World" Express. +The remainder of this article will define and add three middleware functions to the application: +one called `myLogger` that prints a simple log message, one called `requestTime` that +displays the timestamp of the HTTP request, and one called `validateCookies` that validates incoming cookies. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +### Função Middleware myLogger + +Aqui está um exemplo simples de uma função de middleware chamada "myLogger". Essa função apenas imprime +"LOGGGED" quando uma solicitação para o aplicativo passa por ela. A função middleware está atribuída a uma variável +chamada `myLogger`. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGGED'); + next(); +}; +``` + + + +Observe a chamada acima para `next()`. Chamar esta função chama a próxima função de middleware em +o aplicativo. A função `next()` não é parte do Node. s ou API Expressa, mas é o terceiro argumento +que é passado para a função middleware. A função `next()` pode ser nomeada qualquer coisa, +mas por convenção é sempre chamada de "next". Para evitar confusões, utilize sempre esta convenção. + + + +Para carregar a função middleware, chame `app.use()`, especificando a função middleware. +Por exemplo, o código a seguir carrega a função `myLogger` middleware antes da rota para o caminho raiz (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console. og('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +Toda vez que o aplicativo recebe uma solicitação, ele imprime a mensagem "LOGGED" no terminal. + +A ordem do carregamento do middleware é importante: as funções de middleware que são carregadas primeiro também são executadas primeiro. + +Se o `myLogger` é carregado após a rota para o caminho raiz, a solicitação nunca chega a ela e o aplicativo não imprime "LOGGED", porque o gerenciador de rotas do caminho raiz termina o ciclo de resposta-requisição. + +A função middleware `myLogger` simplesmente imprime uma mensagem, então passa a requisição para a próxima função de middleware na pilha chamando a função `next()`. + +### Tempo de solicitação de função Middleware + +Em seguida, vamos criar uma função middleware chamada "requestTime" e adicionar uma propriedade chamada `requestTime` +ao objeto solicitado. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +O aplicativo agora usa a função middleware `requestTime`. Além disso, a função de retorno de chamada da rota raiz usa a propriedade que a função middleware adiciona a `req` (o objeto de solicitação). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req. equestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +aplicativo. et('/', (req, res) => { + let responseText = 'Olá Mundo!
'; + responseText += `Solicitado em: ${req.requestTime}`; + res. end(responseText); +}); + +app.listen(3000); +``` + +Quando você faz uma solicitação na raiz do aplicativo, o aplicativo agora mostra a marcação de hora da sua solicitação no navegador. + +### Função Middleware validateCookies + +Finalmente, vamos criar uma função de middleware que valida os cookies recebidos e envia uma resposta de 400 se cookies forem inválidos. + +Aqui está uma função de exemplo que valida cookies com um serviço assíncrono externo. + +```js +função assíncrona cookieValidator(cookies) { + tente { + aguarde externamenteCookie(cookies.testCookie); + } pesque { + throw new Error('Cookies inválidos'); + } +} +``` + +Aqui, usamos o [`cookie-parser`](/en/resources/middleware/cookie-parser) middleware para analisar cookies recebidos do objeto `req` e passá-los para a nossa função `cookieValidator`. O middleware 'validateCookies' retorna a promessa de que, após a rejeição, irá automaticamente acionar o nosso manipulador de erros. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('. cookieValidator'); + +const app = express(); + +função async validateCookies(req, res, next) { + aguarde cookieValidator(req. ookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// manipulador de erro +. se((err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Observe como `next()` é chamado depois `await cookieValidator(req.cookies)`. Isto garante que se +`cookieValidator` resolver, o próximo middleware na pilha será chamado. Se você passar qualquer coisa +para a função `next()` (exceto a string `'route'` ou `'router'`), Expresse que a solicitação +atual é um erro e pulará quaisquer funções que ainda não sejam de manipulação de erros e de middleware +. + + + +Como você tem acesso ao objeto de solicitação, o objeto de resposta, a próxima função de middleware na pilha, e todo o nó. s API, as possibilidades com funções de middleware são infinitas. + +Para mais informações sobre Express middleware, veja: [Usando Express middleware](/en/guide/using-middleware). + +## middleware configurável + +Se precisar de seu middleware para ser configurável, exporte uma função que aceite um objeto de opções ou outros parâmetros, que então retorna a implementação intermediária com base nos parâmetros de entrada. + +Arquivo: `meu-middleware.js` + +```js +Módulo xports = função (opcions) { + return function (req, next) { + // Implementa a função middleware baseada no objeto de opções + next(); + }; +}; +``` + +O middleware agora pode ser usado como mostrado abaixo. + +```js +const mw = require('./meu-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Consulte [cookie-session](https://github.com/expressjs/cookie-session) e [compression](https://github.com/expressjs/compression) para ver exemplos de intermediário configurável. diff --git a/src/content/docs/pt-br/5x/starter/basic-routing.mdx b/src/content/docs/pt-br/5x/starter/basic-routing.mdx new file mode 100644 index 0000000000..ea9db985e3 --- /dev/null +++ b/src/content/docs/pt-br/5x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Roteamento básico +description: Aprenda os fundamentos do roteamento em aplicações Express.js, incluindo como definir rotas, lidar com métodos HTTP e criar manipuladores de rotas para seu servidor web. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* refere-se a determinar como uma aplicação responde a uma solicitação do cliente para um ponto final específico, que é um URI (ou caminho) e um método de requisição HTTP específico (GET, POST, e assim por diante). + +Cada rota pode ter uma ou mais funções de manipulador, que são executadas quando a rota é correspondente. + +A definição de rota aceita a seguinte estrutura: + +```js +app.METHOD(PATH, MUITO); +``` + +Onde: + +* `app` é uma instância de `express`. +* `METHOD` é um [método de solicitação HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), em minúsculas. +* O `PATH` é um caminho no servidor. +* `HANDLER` é a função executada quando a rota é correspondente. + + + +This tutorial assumes that an instance of `express` named `app` is created and the server is +running. Se você não estiver familiarizado com a criação de um aplicativo e iniciando-o, consulte Olá mundo +exemplo. + + + +Os exemplos seguintes ilustram a definição de rotas simples. + +Responda com `Olá Mundo!` na página inicial: + +```js +app.get('/', (req, res) => { + res.send('Olá Mundo!'); +}); +``` + +Responder a uma solicitação POST na rota raiz (`/`), a página inicial do aplicativo: + +```js +app.post('/', (req, res) => { + res.send('Tem uma solicitação POST'); +}); +``` + +Responda a uma solicitação PUT para a rota `/user`: + +```js +app.put('/user', (req, res) => { + res.send('Tem uma solicitação de PUT em/user'); +}); +``` + +Responder a uma solicitação de DELETE para a rota `/user`: + +```js +app.delete('/user', (req, res) => { + res.send('Tem uma solicitação de DELETE em/user'); +}); +``` + +Para mais detalhes sobre roteamento, consulte o [guia de roteamento](/en/guide/routing). diff --git a/src/content/docs/pt-br/5x/starter/examples.mdx b/src/content/docs/pt-br/5x/starter/examples.mdx new file mode 100644 index 0000000000..7f0f80668c --- /dev/null +++ b/src/content/docs/pt-br/5x/starter/examples.mdx @@ -0,0 +1,49 @@ +--- +title: Exemplos expressos +description: Explore uma coleção de exemplos de aplicativos do Express.js cobrindo vários casos de uso, integrações e configurações avançadas para ajudá-lo a aprender e construir seus projetos. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Esta página contém a lista de exemplos usando o Express. + +* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Autenticação com login e senha +* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - negociação de conteúdo HTTP +* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Trabalhando com sessões baseadas em cookies +* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Trabalhando com cookies +* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transferindo arquivos para o cliente +* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Trabalhando com template JavaScript embutido (ejs) +* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Criando páginas de erro +* [error](https://github.com/expressjs/express/tree/master/examples/error) - Trabalhando com um middleware de erro +* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Manipulador de requisições simples +* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown como mecanismo de modelo +* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Trabalhando com vários roteadores Expressos +* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - controladores do estilo MVC +* [online](https://github.com/expressjs/express/tree/master/examples/online) - Rastreando atividade de usuário online com pacotes `online` e `redis` +* [params](https://github.com/expressjs/express/tree/master/examples/params) - Trabalhando com parâmetros de rotas +* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Várias operações HTTP no mesmo recurso +* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organização de rotas usando um mapa +* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Trabalhando com sistema de middleware +* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizando rotas por recurso +* [search](https://github.com/expressjs/express/tree/master/examples/search) - Pesquisa API +* [session](https://github.com/expressjs/express/tree/master/examples/session) - Sessões de usuário +* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Servendo arquivos estáticos +* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Trabalhando com hosts virtuais +* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Renderizando visualizações dinamicamente +* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Salvando dados no objeto da solicitação entre chamadas de middleware +* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Serviço de API simples + +## Exemplos adicionais + +Estes são alguns exemplos adicionais com integrações mais extensas. + + + +Esta informação refere-se a sites de terceiros, produtos ou módulos que não são mantidos pela equipe +Expressjs. Listar aqui não constitui um endosso ou recomendação da equipe de projeto +Expressjs. + + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Aplicativo Fullstack com Express and Next.js usando [Prisma](https://www.npmjs.com/package/prisma) como ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - API REST com Express in TypeScript usando [Prisma](https://www.npmjs.com/package/prisma) como ORM diff --git a/src/content/docs/pt-br/5x/starter/faq.md b/src/content/docs/pt-br/5x/starter/faq.md new file mode 100644 index 0000000000..8af6c95239 --- /dev/null +++ b/src/content/docs/pt-br/5x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: Perguntas Frequentes +description: Encontre respostas para perguntas frequentes sobre Express.js, incluindo tópicos sobre a estrutura do aplicativo, modelos, autenticação, mecanismos de modelo, tratamento de erros e muito mais. +--- + +## Como eu devo estruturar meu aplicativo? + +Não há uma resposta definitiva a esta questão. A resposta depende +da escala do seu aplicativo e da equipe que está envolvida. Para ser o mais flexível possível, +flexível, Express não faz suposições em termos de estrutura. + +Rotas e outras lógicas específicas do aplicativo podem viver em quantos arquivos +você quiser, em qualquer estrutura de diretório que preferir. View the following +examples for inspiration: + +- [Lista de rotas](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Mapa de rotas](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Além disso, existem extensões para o Express, que simplificam alguns desses padrões: + +- [Roteamento de recursos](https://github.com/expressjs/express-resource) + +## Como faço para definir modelos? + +Expresso não tem noção de um banco de dados. This concept is +left up to third-party Node modules, allowing you to +interface with nearly any database. + +Veja [LoopBack](http://loopback.io) para um framework baseado em Express que é centralizado em torno de modelos. + +## Como posso autenticar os usuários? + +Authentication is another opinionated area that Express does not +venture into. Você pode usar qualquer esquema de autenticação desejado. +Para um esquema simples de nome de usuário/senha, consulte [este exemplo](https://github.com/expressjs/express/tree/master/examples/auth). + +## Quais mecanismos de template suporta o Expresso? + +Expresso suporta qualquer mecanismo de modelos que esteja em conformidade com a assinatura `(caminho, moradores, callback)`. +Para normalizar interfaces do motor de modelos e cache de cache, veja o projeto +[consolidate.js](https://github.com/visionmedia/consolidate.js) +para suporte. Motores de modelos não listados ainda podem suportar a assinatura Express. + +Para obter mais informações, consulte [Usando mecanismos de modelo com Express](/en/guide/using-template-engines). + +## Como lidamos com 404 respostas? + +Em Express, respostas 404 não são resultado de um erro, então +o middleware de erro não as capturará. This behavior is +because a 404 response simply indicates the absence of additional work to do; +in other words, Express has executed all middleware functions and routes, +and found that none of them responded. All you need to +do is add a middleware function at the very bottom of the stack (below all other functions) +to handle a 404 response: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Adicione rotas dinamicamente em tempo de execução em uma instância de `express.Router()` +para que as rotas não sejam substituídas por uma função middleware. + +## Como faço para configurar um manipulador de erro? + +Você define o middleware com erros de manipulação da mesma forma que outros middleware, +exceto com quatro argumentos em vez de três; especificamente com a assinatura `(err, req, res, próxima)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +Para obter mais informações, consulte [Manipulação de erro](/en/guide/error-handling). + +## Como faço para tornar HTML simples? + +Você não! Não há necessidade de "render" HTML com a função `res.render()`. +Se você tiver um arquivo específico, use a função `res.sendFile()`. +Se você estiver servindo muitos assets de um diretório, use a função `express.static()` +middleware. + +## Qual versão do Node.js requer o Expresso? + +- [Expresso 4.x](/en/4x/api) requer Node.js 0.10 ou superior. +- [Express 5.x](/en/5x/api) requer Node.js 18 ou superior. diff --git a/src/content/docs/pt-br/5x/starter/generator.mdx b/src/content/docs/pt-br/5x/starter/generator.mdx new file mode 100644 index 0000000000..d2c4fade8e --- /dev/null +++ b/src/content/docs/pt-br/5x/starter/generator.mdx @@ -0,0 +1,127 @@ +--- +title: Gerador de aplicação expressa +description: Aprenda a usar a ferramenta gerador de aplicativo Express para criar rapidamente um esqueleto para seus aplicativos Express.js, otimização de configuração e configuração. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Use a ferramenta de gerador de aplicação, `express-generator`, para criar rapidamente um esqueleto de aplicação. + +Você pode executar o gerador de aplicação com o comando `npx` (disponível em Node.js 8.2.0). + +```bash +$ gerador de expressão npx +``` + +Para versões anteriores do Nó, instale o gerador de aplicativo como um pacote npm global e, em seguida, inicie-o: + +```bash +$ npm install -g express-generator +$ express +``` + +Exibe as opções de comando com a opção '-h': + +```bash +$ express -h + + Uso: express [options] [dir] + + Opções: + + -h, --help mostra informação de uso + --version mostra o número da versão + -e, --ejs add ejs engine suporte + --hbs add handlebars engine support + --pug add pug engine support + -H, --hogan adiciona hogan. s mecanismo suporta + --no-view gera sem o mecanismo de exibição + -v, --view add view support (ejs├hbs─jsėjade├jade├pug├twig├vash) (o padrão é jade) + -c, --css add stylesheet (menos:stylus➲ bússola) (o padrão é sem css) + --git add . itignore + -f, --force força em diretório não-vazio +``` + +Por exemplo, o seguinte cria um aplicativo Expresso chamado *myapp*. O aplicativo será criado em uma pasta chamada *myapp* no diretório de trabalho atual e o mecanismo de visualização será definido para Pug: + +```bash +$ express --view=pug meuapp + + create : meuapp + create : myapp/package.json + create : myapp/app. s + criam : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index. s + criar: meuapp/rotas/usuários. s + cria : myapp/public/stylesheets + create : myapp/public/stylesheets/style. ss + cria : myapp/views + criar : myapp/views/index. ug + criar : myapp/views/layout.pug + criar : myapp/views/error. ug + create : myapp/bin + create : myapp/bin/www +``` + +Em seguida, instale dependências: + +```bash +$ cd myapp +$ npm install +``` + +No MacOS ou Linux, execute o aplicativo com este comando: + +```bash +$ DEBUG=meuapp:* npm start +``` + +No prompt de comando Windows, use este comando: + +```bash +> definir DEBUG=myapp:* & npm start +``` + +No Windows PowerShell, use este comando: + +```bash +PS> $env:DEBUG='myapp:*'; npm start +``` + +Em seguida, carregue `http://localhost:3000/` no seu navegador para acessar o aplicativo. + +O aplicativo gerado possui a seguinte estrutura de diretórios: + +```bash +. +── app.js +─── bin +├── www +package. son +── public +── imagens +├── javascripts +├── stylesheets +── style styesheets + ─ style. ss +── rotas +├── index.js +─── usuarios +. s +── visões + erros de ── . ug + ── index.pug + ── layout.pug + +diretórios e 9 arquivos +``` + + + +A estrutura do aplicativo criada pelo gerador é apenas uma das muitas maneiras de estruturar aplicativos Express. +Sinta-se livre para usar esta estrutura ou modificá-la para atender às suas necessidades. + + diff --git a/src/content/docs/pt-br/5x/starter/hello-world.mdx b/src/content/docs/pt-br/5x/starter/hello-world.mdx new file mode 100644 index 0000000000..0680e55315 --- /dev/null +++ b/src/content/docs/pt-br/5x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Olá, exemplo do mundo +description: Comece com o Express.js construindo uma simples aplicação 'Hello World'', demonstrando a configuração básica e a criação de servidor para iniciantes. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Embutido abaixo é essencialmente o aplicativo Expresso mais simples que você pode criar. É um único aplicativo de arquivo +— *não* o que você obteria se usar o [Express generator](/en/starter/generator), que +cria o andaime para um aplicativo completo com vários arquivos JavaScript, modelos Jade e subdiretórios +para vários fins. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res. end('Olá Mundo!'); +}); + +app.listen(port, () => { + console.log(`Exemplo app escutando na porta ${port}`); +}); +``` + +Este aplicativo inicia um servidor e escuta na porta 3000 para conexões. O aplicativo responde com "Olá Mundo!" para solicitações +para a URL raiz (`/`) ou *route*. Para todos os outros caminhos, responderá com um **404 Não Encontrado**. + +## Executando localmente + +Primeiro, crie um diretório chamado `myapp`, mude para ele e execute `npm init`. Em seguida, instale `express` como uma dependência, conforme o [guia de instalação](/en/starter/installing). + +No diretório `myapp`, crie um arquivo chamado `app.js` e copie o código do exemplo acima. + + + +O `req` (requisição) e `res` (resposta) são exatamente os mesmos objetos que o Node fornece, para que você possa +invocar `req. ipe()`, `req.on('data', callback)`, e qualquer outra coisa que você faria sem o Express +envolvido. + + + +Execute o aplicativo com o seguinte comando: + +```bash +$ node app.js +``` + +Em seguida, carregue `http://localhost:3000/` em um navegador para ver a saída. diff --git a/src/content/docs/pt-br/5x/starter/installing.mdx b/src/content/docs/pt-br/5x/starter/installing.mdx new file mode 100644 index 0000000000..b01c680fef --- /dev/null +++ b/src/content/docs/pt-br/5x/starter/installing.mdx @@ -0,0 +1,41 @@ +--- +title: Instalando +description: Aprenda a instalar o Express.js no seu ambiente Node.js, incluindo a configuração do diretório do seu projeto e o gerenciamento de dependências com npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Antes de começar, certifique-se de ter [Node.js](https://nodejs.org/) 18 ou superior instalado. Em seguida, crie um diretório para a sua aplicação e navegue até ele. + +```bash +mkdir myapp +cd myapp +``` + +Use o comando `npm init` para criar um arquivo `package.json` para sua aplicação. +Para obter mais informações sobre como funciona o arquivo `package.json`, veja [Especificações da manipulação do package.json do npm](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +Este comando avisa você para várias coisas, como o nome e a versão de seu aplicativo. +Por enquanto, você simplesmente pode clicar em RETURN para aceitar os padrões para a maioria deles, com a seguinte exceção: + +``` +ponto de entrada: (index.js) +``` + +Digite `app.js`, ou o que quiser que o nome do arquivo principal seja. Se você quer que seja `index.js`, pressione RETURN para aceitar o nome de arquivo padrão sugerido. + +Agora, instale o Express no diretório `myapp` e salve-o na lista de dependências. Por exemplo: + +```bash +Instalação npm expressiva +``` + +Para instalar o Express temporariamente e não adicioná-lo à lista de dependências: + +```bash +npm install express --no-save +``` diff --git a/src/content/docs/pt-br/5x/starter/static-files.mdx b/src/content/docs/pt-br/5x/starter/static-files.mdx new file mode 100644 index 0000000000..dcd21f0ab2 --- /dev/null +++ b/src/content/docs/pt-br/5x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Servindo arquivos estáticos no Express +description: Entenda como servir arquivos estáticos como imagens, CSS e JavaScript em aplicativos Express.js usando o middleware "static". +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Para servir arquivos estáticos como imagens, arquivos CSS e arquivos JavaScript, use a função `express.static` middleware embutida no Express. + +A assinatura da função é: + +```js +express.static(root, [options]); +``` + +O argumento `root` especifica o diretório raiz do qual se destinam os assets estáticos. +Para obter mais informações sobre o argumento `options`, consulte [express.static](/en/5x/api#express.static). + +Por exemplo, use o seguinte código para servir imagens, arquivos CSS e arquivos JavaScript em um diretório chamado `public`: + +```js +app.use(express.static('público')); +``` + +Agora, você pode carregar os arquivos que estão no diretório `public`: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Expresso procura os arquivos relativos ao diretório estático, então o nome do diretório estático +não faz parte do URL. + + + +Para usar vários diretórios de ativos estáticos, chame a função `express.static` middleware várias vezes: + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Expresso olha os arquivos na ordem em que você definiu os diretórios estáticos com a função de middleware `express.static`. + + + +Para melhores resultados, use um proxy +reverso cache para melhorar o desempenho do +servindo ativos estáticos. + + + +Para criar um prefixo de caminho virtual (onde o caminho não existe realmente no sistema de arquivos) para arquivos que são servidos pelo `express. função tática`, [especifique um caminho de montagem](/en/5x/api#app.use) para o diretório estático, conforme mostrado abaixo: + +```js +app.use('/static', express.static('public')); +``` + +Agora, você pode carregar os arquivos que estão no diretório `public` a partir do prefixo de caminho `/static`. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +No entanto, o caminho que você fornece para a função `express.static` é relativo ao diretório de onde você inicia seu processo `node`. Se você executar o aplicativo expresso a partir de outro diretório, é mais seguro usar o caminho absoluto do diretório que você deseja servir: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public'))); +``` + +Para mais detalhes sobre a função `serve-static` e suas opções, consulte [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/zh-tw/4x/advanced/developing-template-engines.md b/src/content/docs/zh-tw/4x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..6e9710fbc5 --- /dev/null +++ b/src/content/docs/zh-tw/4x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Developing template engines for Express +description: Learn how to develop custom template engines for Express.js using app.engine(), with examples on creating and integrating your own template rendering logic. +--- + +Use the `app.engine(ext, callback)` method to create your own template engine. `ext` refers to the file extension, and `callback` is the template engine function, which accepts the following items as parameters: the location of the file, the options object, and the callback function. + +The following code is an example of implementing a very simple template engine for rendering `.ntl` files. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +Your app will now be able to render `.ntl` files. Create a file named `index.ntl` in the `views` directory with the following content. + +```pug +#title# +#message# +``` + +Then, create the following route in your app. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +When you make a request to the home page, `index.ntl` will be rendered as HTML. diff --git a/src/content/docs/zh-tw/4x/guide/behind-proxies.mdx b/src/content/docs/zh-tw/4x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..dc509998f7 --- /dev/null +++ b/src/content/docs/zh-tw/4x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Express behind proxies +description: Learn how to configure Express.js applications to work correctly behind reverse proxies, including using the trust proxy setting to handle client IP addresses. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +When running an Express app behind a reverse proxy, some of the Express APIs may return different values than expected. In order to adjust for this, the `trust proxy` application setting may be used to expose information provided by the reverse proxy in the Express APIs. The most common issue is express APIs that expose the client's IP address may instead show an internal IP address of the reverse proxy. + + + +When configuring the `trust proxy` setting, it is important to understand the exact setup of the +reverse proxy. Since this setting will trust values provided in the request, it is important that +the combination of the setting in Express matches how the reverse proxy operates. + + + +The application setting `trust proxy` may be set to one of the values listed in the following table. + + + + + + + + + + + + + + + + + + + + + +
TypeValue
Boolean +If `true`, the client's IP address is understood as the left-most entry in the `X-Forwarded-For` header. + +If `false`, the app is understood as directly facing the client and the client's IP address is derived from `req.socket.remoteAddress`. This is the default setting. + + +When setting to `true`, it is important to ensure that the last reverse proxy trusted is removing/overwriting all of the following HTTP headers: `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`, otherwise it may be possible for the client to provide any value. + +
IP addresses +An IP address, subnet, or an array of IP addresses and subnets to trust as being a reverse proxy. The following list shows the pre-configured subnet names: + +* loopback - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +You can set IP addresses in any of the following ways: + +```js +app.set('trust proxy', 'loopback'); // specify a single subnet +app.set('trust proxy', 'loopback, 123.123.123.123'); // specify a subnet and an address +app.set('trust proxy', 'loopback, linklocal, uniquelocal'); // specify multiple subnets as CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // specify multiple subnets as an array +``` + +When specified, the IP addresses or the subnets are excluded from the address determination process, and the untrusted IP address nearest to the application server is determined as the client's IP address. This works by checking if `req.socket.remoteAddress` is trusted. If so, then each address in `X-Forwarded-For` is checked from right to left until the first non-trusted address. + +
Number +Use the address that is at most `n` number of hops away from the Express application. `req.socket.remoteAddress` is the first hop, and the rest are looked for in the `X-Forwarded-For` header from right to left. A value of `0` means that the first untrusted address would be `req.socket.remoteAddress`, i.e. there is no reverse proxy. + + +When using this setting, it is important to ensure there are not multiple, different-length paths to the Express application such that the client can be less than the configured number of hops away, otherwise it may be possible for the client to provide any value. + +
Function +Custom trust implementation. + +```js +app.set('trust proxy', (ip) => { + if (ip === '127.0.0.1' || ip === '123.123.123.123') + return true; // trusted IPs + else return false; +}); +``` + +
+ +Enabling `trust proxy` will have the following impact: + +
    +
  • + The value of [req.hostname](/en/api#req.hostname) is derived from the value set in the + `X-Forwarded-Host` header, which can be set by the client or by the proxy. +
    • +
  • + `X-Forwarded-Proto` can be set by the reverse proxy to tell the app whether it is `https` or + `http` or even an invalid name. This value is reflected by [req.protocol](/en/api#req.protocol). +
    • +
  • + The [req.ip](/en/api#req.ip) and [req.ips](/en/api#req.ips) values are populated based on the + socket address and `X-Forwarded-For` header, starting at the first untrusted address. +
    • +
+ +The `trust proxy` setting is implemented using the [proxy-addr](https://www.npmjs.com/package/proxy-addr) package. For more information, see its documentation. diff --git a/src/content/docs/zh-tw/4x/guide/debugging.mdx b/src/content/docs/zh-tw/4x/guide/debugging.mdx new file mode 100644 index 0000000000..a7750f5427 --- /dev/null +++ b/src/content/docs/zh-tw/4x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Debugging Express +description: Learn how to enable and use debugging logs in Express.js applications by setting the DEBUG environment variable for enhanced troubleshooting. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +To see all the internal logs used in Express, set the `DEBUG` environment variable to +`express:*` when launching your app. + +```bash +$ DEBUG=express:* node index.js +``` + +On Windows, use the corresponding command. + +```bash +> $env:DEBUG = "express:*"; node index.js +``` + +Running this command on the default app generated by the [express generator](/en/starter/generator) prints the following output: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +When a request is then made to the app, you will see the logs specified in the Express code: + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index.pug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +To see the logs only from the router implementation, set the value of `DEBUG` to `express:router`. Likewise, to see logs only from the application implementation, set the value of `DEBUG` to `express:application`, and so on. + +## Applications generated by `express` + +An application generated by the `express` command uses the `debug` module and its debug namespace is scoped to the name of the application. + +For example, if you generated the app with `$ express sample-app`, you can enable the debug statements with the following command: + +```bash +$ DEBUG=sample-app:* node ./bin/www +``` + +You can specify more than one debug namespace by assigning a comma-separated list of names: + +```bash +$ DEBUG=http,mail,express:* node index.js +``` + +## Advanced options + +When running through Node.js, you can set a few environment variables that will change the behavior of the debug logging: + +| Name | Purpose | +| ------------------- | ------------------------------------------------- | +| `DEBUG` | Enables/disables specific debugging namespaces. | +| `DEBUG_COLORS` | Whether or not to use colors in the debug output. | +| `DEBUG_DEPTH` | Object inspection depth. | +| `DEBUG_FD` | File descriptor to write debug output to. | +| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. | + + + +The environment variables beginning with `DEBUG_` end up being converted into an Options object +that gets used with `%o`/`%O` formatters. See the Node.js documentation for +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) for the complete +list. + + diff --git a/src/content/docs/zh-tw/4x/guide/error-handling.mdx b/src/content/docs/zh-tw/4x/guide/error-handling.mdx new file mode 100644 index 0000000000..78f1c86e92 --- /dev/null +++ b/src/content/docs/zh-tw/4x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Error Handling +description: Understand how Express.js handles errors in synchronous and asynchronous code, and learn to implement custom error handling middleware for your applications. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Error Handling* refers to how Express catches and processes errors that +occur both synchronously and asynchronously. Express comes with a default error +handler so you don't need to write your own to get started. + +## Catching Errors + +It's important to ensure that Express catches all errors that occur while +running route handlers and middleware. + +Errors that occur in synchronous code inside route handlers and middleware +require no extra work. If synchronous code throws an error, then Express will +catch and process it. For example: + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Express will catch this on its own. +}); +``` + +For errors returned from asynchronous functions invoked by route handlers +and middleware, you must pass them to the `next()` function, where Express will +catch and process them. For example: + +```js +app.get('/', (req, res, next) => { + fs.readFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Pass errors to Express. + } else { + res.send(data); + } + }); +}); +``` + +Starting with Express 5, route handlers and middleware that return a Promise +will call `next(value)` automatically when they reject or throw an error. +For example: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = await getUserById(req.params.id); + res.send(user); +}); +``` + +If `getUserById` throws an error or rejects, `next` will be called with either +the thrown error or the rejected value. If no rejected value is provided, `next` +will be called with a default Error object provided by the Express router. + +If you pass anything to the `next()` function (except the string `'route'`), +Express regards the current request as being an error and will skip any +remaining non-error handling routing and middleware functions. + +If the callback in a sequence provides no data, only errors, you can simplify +this code as follows: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +In the above example, `next` is provided as the callback for `fs.writeFile`, +which is called with or without errors. If there is no error, the second +handler is executed, otherwise Express catches and processes the error. + +You must catch errors that occur in asynchronous code invoked by route handlers or +middleware and pass them to Express for processing. For example: + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + next(err); + } + }, 100); +}); +``` + +The above example uses a `try...catch` block to catch errors in the +asynchronous code and pass them to Express. If the `try...catch` +block were omitted, Express would not catch the error since it is not part of the synchronous +handler code. + +Use promises to avoid the overhead of the `try...catch` block or when using functions +that return promises. For example: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + .then(() => { + throw new Error('BROKEN'); + }) + .catch(next); // Errors will be passed to Express. +}); +``` + +Since promises automatically catch both synchronous errors and rejected promises, +you can simply provide `next` as the final catch handler and Express will catch errors, +because the catch handler is given the error as the first argument. + +You could also use a chain of handlers to rely on synchronous error +catching, by reducing the asynchronous code to something trivial. For example: + +```js +app.get('/', [ + function (req, res, next) { + fs.readFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals.data = data; + next(err); + }); + }, + function (req, res) { + res.locals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +The above example has a couple of trivial statements from the `readFile` +call. If `readFile` causes an error, then it passes the error to Express, otherwise you +quickly return to the world of synchronous error handling in the next handler +in the chain. Then, the example above tries to process the data. If this fails, then the +synchronous error handler will catch it. If you had done this processing inside +the `readFile` callback, then the application might exit and the Express error +handlers would not run. + +Whichever method you use, if you want Express error handlers to be called in and the +application to survive, you must ensure that Express receives the error. + +## The default error handler + +Express comes with a built-in error handler that takes care of any errors that might be encountered in the app. This default error-handling middleware function is added at the end of the middleware function stack. + +If you pass an error to `next()` and you do not handle it in a custom error +handler, it will be handled by the built-in error handler; the error will be +written to the client with the stack trace. The stack trace is not included +in the production environment. + + + +Set the environment variable `NODE_ENV` to `production`, to run the app in production mode. + + + +When an error is written, the following information is added to the +response: + +* The `res.statusCode` is set from `err.status` (or `err.statusCode`). If + this value is outside the 4xx or 5xx range, it will be set to 500. +* The `res.statusMessage` is set according to the status code. +* The body will be the HTML of the status code message when in production + environment, otherwise will be `err.stack`. +* Any headers specified in an `err.headers` object. + +If you call `next()` with an error after you have started writing the +response (for example, if you encounter an error while streaming the +response to the client), the Express default error handler closes the +connection and fails the request. + +So when you add a custom error handler, you must delegate to +the default Express error handler, when the headers +have already been sent to the client: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Note that the default error handler can get triggered if you call `next()` with an error +in your code more than once, even if custom error handling middleware is in place. + +Other error handling middleware can be found at [Express middleware](/en/resources/middleware). + +## Writing error handlers + +Define error-handling middleware functions in the same way as other middleware functions, +except error-handling functions have four arguments instead of three: +`(err, req, res, next)`. For example: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +You define error-handling middleware last, after other `app.use()` and routes calls; for example: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser.urlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app.use(methodOverride()); +app.use((err, req, res, next) => { + // logic +}); +``` + +Responses from within a middleware function can be in any format, such as an HTML error page, a simple message, or a JSON string. + +For organizational (and higher-level framework) purposes, you can define +several error-handling middleware functions, much as you would with +regular middleware functions. For example, to define an error-handler +for requests made by using `XHR` and those without: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser.urlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +In this example, the generic `logErrors` might write request and +error information to `stderr`, for example: + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +Also in this example, `clientErrorHandler` is defined as follows; in this case, the error is explicitly passed along to the next one. + +Notice that when *not* calling "next" in an error-handling function, you are responsible for writing (and ending) the response. Otherwise, those requests will "hang" and will not be eligible for garbage collection. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500).send({ error: 'Something failed!' }); + } else { + next(err); + } +} +``` + +Implement the "catch-all" `errorHandler` function as follows (for example): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +If you have a route handler with multiple callback functions, you can use the `route` parameter to skip to the next route handler. For example: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user.hasPaid) { + // continue handling this request + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent.find((err, doc) => { + if (err) return next(err); + res.json(doc); + }); + } +); +``` + +In this example, the `getPaidContent` handler will be skipped but any remaining handlers in `app` for `/a_route_behind_paywall` would continue to be executed. + + + +Calls to `next()` and `next(err)` indicate that the current handler is complete and in what state. +`next(err)` will skip all remaining handlers in the chain except for those that are set up to +handle errors as described above. + + diff --git a/src/content/docs/zh-tw/4x/guide/overriding-express-api.md b/src/content/docs/zh-tw/4x/guide/overriding-express-api.md new file mode 100644 index 0000000000..f5281a58f5 --- /dev/null +++ b/src/content/docs/zh-tw/4x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Overriding the Express API +description: Discover how to customize and extend the Express.js API by overriding methods and properties on the request and response objects using prototypes. +--- + +The Express API consists of various methods and properties on the request and response objects. These are inherited by prototype. There are two extension points for the Express API: + +1. The global prototypes at `express.request` and `express.response`. +2. App-specific prototypes at `app.request` and `app.response`. + +Altering the global prototypes will affect all loaded Express apps in the same process. If desired, alterations can be made app-specific by only altering the app-specific prototypes after creating a new app. + +## Methods + +You can override the signature and behavior of existing methods with your own, by assigning a custom function. + +Following is an example of overriding the behavior of [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +The above implementation completely changes the original signature of `res.sendStatus`. It now accepts a status code, encoding type, and the message to be sent to the client. + +The overridden method may now be used this way: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## Properties + +Properties in the Express API are either: + +1. Assigned properties (ex: `req.baseUrl`, `req.originalUrl`) +2. Defined as getters (ex: `req.secure`, `req.ip`) + +Since properties under category 1 are dynamically assigned on the `request` and `response` objects in the context of the current request-response cycle, their behavior cannot be overridden. + +Properties under category 2 can be overwritten using the Express API extensions API. + +The following code rewrites how the value of `req.ip` is to be derived. Now, it simply returns the value of the `Client-IP` request header. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Prototype + +In order to provide the Express API, the request/response objects passed to Express (via `app(req, res)`, for example) need to inherit from the same prototype chain. By default, this is `http.IncomingRequest.prototype` for the request and `http.ServerResponse.prototype` for the response. + +Unless necessary, it is recommended that this be done only at the application level, rather than globally. Also, take care that the prototype that is being used matches the functionality as closely as possible to the default prototypes. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/zh-tw/4x/guide/routing.mdx b/src/content/docs/zh-tw/4x/guide/routing.mdx new file mode 100644 index 0000000000..78ab64f6e8 --- /dev/null +++ b/src/content/docs/zh-tw/4x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Routing +description: Learn how to define and use routes in Express.js applications, including route methods, route paths, parameters, and using Router for modular routing. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* refers to how an application's endpoints (URIs) respond to client requests. +For an introduction to routing, see [Basic routing](/en/starter/basic-routing). + +You define routing using methods of the Express `app` object that correspond to HTTP methods; +for example, `app.get()` to handle GET requests and `app.post` to handle POST requests. For a full list, +see [app.METHOD](/en/5x/api#app.METHOD). You can also use [app.all()](/en/5x/api#app.all) to handle all HTTP methods and [app.use()](/en/5x/api#app.use) to +specify middleware as the callback function (See [Using middleware](/en/guide/using-middleware) for details). + +These routing methods specify a callback function (sometimes called "handler functions") called when the application receives a request to the specified route (endpoint) and HTTP method. In other words, the application "listens" for requests that match the specified route(s) and method(s), and when it detects a match, it calls the specified callback function. + +In fact, the routing methods can have more than one callback function as arguments. +With multiple callback functions, it is important to provide `next` as an argument to the callback function and then call `next()` within the body of the function to hand off control +to the next callback. + +The following code is an example of a very basic route. + +```js +const express = require('express'); +const app = express(); + +// respond with "hello world" when a GET request is made to the homepage +app.get('/', (req, res) => { + res.send('hello world'); +}); +``` + +## Route methods + +A route method is derived from one of the HTTP methods, and is attached to an instance of the `express` class. + +The following code is an example of routes that are defined for the `GET` and the `POST` methods to the root of the app. + +```js +// GET method route +app.get('/', (req, res) => { + res.send('GET request to the homepage'); +}); + +// POST method route +app.post('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Express supports methods that correspond to all HTTP request methods: `get`, `post`, and so on. +For a full list, see [app.METHOD](/en/5x/api#app.METHOD). + +There is a special routing method, `app.all()`, used to load middleware functions at a path for *all* HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Accessing the secret section ...'); + next(); // pass control to the next handler +}); +``` + +## Route paths + +Route paths, in combination with a request method, define the endpoints at which requests can be made. Route paths can be strings, string patterns, or regular expressions. + + + +In express 5, the characters `?`, `+`, `*`, `[]`, and `()` are handled differently than in version +4, please review the [migration guide](/en/guide/migrating-5#path-syntax) for more information. + + + + + +In express 4, regular expression characters such as `$` need to be escaped with a `\`. + + + + + +Express uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) for matching the route +paths; see the path-to-regexp documentation for all the possibilities in defining route paths. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) is a handy tool for +testing basic Express routes, although it does not support pattern matching. + + + +Query strings are not part of the route path. + +### Route paths based on strings + +This route path will match requests to the root route, `/`. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +This route path will match requests to `/about`. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +This route path will match requests to `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Route paths based on string patterns + + + +The string patterns in Express 5 no longer work. Please refer to the migration +guide for more information. + + + +This route path will match `acd` and `abcd`. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +This route path will match `abcd`, `abbcd`, `abbbcd`, and so on. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +This route path will match `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd`, and so on. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +This route path will match `/abe` and `/abcde`. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Route paths based on regular expressions + +This route path will match anything with an "a" in it. + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +This route path will match `butterfly` and `dragonfly`, but not `butterflyman`, `dragonflyman`, and so on. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Route parameters + +Route parameters are named URL segments that are used to capture the values specified at their position in the URL. The captured values are populated in the `req.params` object, with the name of the route parameter specified in the path as their respective keys. + +``` +Route path: /users/:userId/books/:bookId +Request URL: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +To define routes with route parameters, simply specify the route parameters in the path of the route as shown below. + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +The name of route parameters must be made up of "word characters" ([A-Za-z0-9_]). + + + +Since the hyphen (`-`) and the dot (`.`) are interpreted literally, they can be used along with route parameters for useful purposes. + +``` +Route path: /flights/:from-:to +Request URL: http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Route path: /plantae/:genus.:species +Request URL: http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +In express 5, Regexp characters are not supported in route paths, for more information please +refer to the [migration guide](/en/guide/migrating-5#path-syntax). + + + +To have more control over the exact string that can be matched by a route parameter, you can append a regular expression in parentheses (`()`): + +``` +Route path: /user/:userId(\d+) +Request URL: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Because the regular expression is usually part of a literal string, be sure to escape any `\` +characters with an additional backslash, for example `\d+`. + + + + +In Express 4.x, the `*` character in regular expressions is not interpreted in the usual way. As a workaround, use `{0,}` instead of `*`. This will likely be fixed in Express 5. + + +## Route handlers + +You can provide multiple callback functions that behave like [middleware](/en/guide/using-middleware) to handle a request. The only exception is that these callbacks might invoke `next('route')` to bypass the remaining route callbacks. You can use this mechanism to impose pre-conditions on a route, then pass control to subsequent routes if there's no reason to proceed with the current route. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params.id === '0') { + return next('route'); + } + res.send(`User ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Special handler for user ID 0'); +}); +``` + +In this example: + +* `GET /user/5` → handled by first route → sends "User 5" +* `GET /user/0` → first route calls `next('route')`, skipping to the next matching `/user/:id` route + +Route handlers can be in the form of a function, an array of functions, or combinations of both, as shown in the following examples. + +A single callback function can handle a route. For example: + +```js +app.get('/example/a', (req, res) => { + res.send('Hello from A!'); +}); +``` + +More than one callback function can handle a route (make sure you specify the `next` object). For example: + +```js +app.get( + '/example/b', + (req, res, next) => { + console.log('the response will be sent by the next function ...'); + next(); + }, + (req, res) => { + res.send('Hello from B!'); + } +); +``` + +An array of callback functions can handle a route. For example: + +```js +const cb0 = function (req, res, next) { + console.log('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console.log('CB1'); + next(); +}; + +const cb2 = function (req, res) { + res.send('Hello from C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +A combination of independent functions and arrays of functions can handle a route. For example: + +```js +const cb0 = function (req, res, next) { + console.log('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console.log('CB1'); + next(); +}; + +app.get( + '/example/d', + [cb0, cb1], + (req, res, next) => { + console.log('the response will be sent by the next function ...'); + next(); + }, + (req, res) => { + res.send('Hello from D!'); + } +); +``` + +## Response methods + +The methods on the response object (`res`) in the following table can send a response to the client, and terminate the request-response cycle. If none of these methods are called from a route handler, the client request will be left hanging. + +| Method | Description | +| --------------------------------------------- | ------------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | Prompt a file to be downloaded. | +| [res.end()](/en/5x/api#res.end) | End the response process. | +| [res.json()](/en/5x/api#res.json) | Send a JSON response. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Send a JSON response with JSONP support. | +| [res.redirect()](/en/5x/api#res.redirect) | Redirect a request. | +| [res.render()](/en/5x/api#res.render) | Render a view template. | +| [res.send()](/en/5x/api#res.send) | Send a response of various types. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Send a file as an octet stream. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Set the response status code and send its string representation as the response body. | + +## app.route() + +You can create chainable route handlers for a route path by using `app.route()`. +Because the path is specified at a single location, creating modular routes is helpful, as is reducing redundancy and typos. For more information about routes, see: [Router() documentation](/en/5x/api#router). + +Here is an example of chained route handlers that are defined by using `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res.send('Get a random book'); + }) + .post((req, res) => { + res.send('Add a book'); + }) + .put((req, res) => { + res.send('Update the book'); + }); +``` + +## express.Router + +Use the `express.Router` class to create modular, mountable route handlers. A `Router` instance is a complete middleware and routing system; for this reason, it is often referred to as a "mini-app". + +The following example creates a router as a module, loads a middleware function in it, defines some routes, and mounts the router module on a path in the main app. + +Create a router file named `birds.js` in the app directory, with the following content: + +```js +const express = require('express'); +const router = express.Router(); + +// middleware that is specific to this router +const timeLog = (req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}; +router.use(timeLog); + +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Then, load the router module in the app: + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +The app will now be able to handle requests to `/birds` and `/birds/about`, as well as call the `timeLog` middleware function that is specific to the route. + +But if the parent route `/birds` has path parameters, it will not be accessible by default from the sub-routes. To make it accessible, you will need to pass the `mergeParams` option to the Router constructor [reference](/en/5x/api#app.use). + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/zh-tw/4x/guide/using-middleware.mdx b/src/content/docs/zh-tw/4x/guide/using-middleware.mdx new file mode 100644 index 0000000000..026542a234 --- /dev/null +++ b/src/content/docs/zh-tw/4x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Using middleware +description: Learn how to use middleware in Express.js applications, including application-level and router-level middleware, error handling, and integrating third-party middleware. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express is a routing and middleware web framework that has minimal functionality of its own: An Express application is essentially a series of middleware function calls. + +*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. + +Middleware functions can perform the following tasks: + +* Execute any code. +* Make changes to the request and the response objects. +* End the request-response cycle. +* Call the next middleware function in the stack. + +If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. + +An Express application can use the following types of middleware: + +* [Application-level middleware](#middleware.application) +* [Router-level middleware](#middleware.router) +* [Error-handling middleware](#middleware.error-handling) +* [Built-in middleware](#middleware.built-in) +* [Third-party middleware](#middleware.third-party) + +You can load application-level and router-level middleware with an optional mount path. +You can also load a series of middleware functions together, which creates a sub-stack of the middleware system at a mount point. + +## Application-level middleware + +Bind application-level middleware to an instance of the [app object](/en/5x/api#app) by using the `app.use()` and `app.METHOD()` functions, where `METHOD` is the HTTP method of the request that the middleware function handles (such as GET, PUT, or POST) in lowercase. + +This example shows a middleware function with no mount path. The function is executed every time the app receives a request. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +This example shows a middleware function mounted on the `/user/:id` path. The function is executed for any type of +HTTP request on the `/user/:id` path. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +This example shows a route and its handler function (middleware system). The function handles GET requests to the `/user/:id` path. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +Here is an example of loading a series of middleware functions at a mount point, with a mount path. +It illustrates a middleware sub-stack that prints request info for any type of HTTP request to the `/user/:id` path. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); +``` + +Route handlers enable you to define multiple routes for a path. The example below defines two routes for GET requests to the `/user/:id` path. The second route will not cause any problems, but it will never get called because the first route ends the request-response cycle. + +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req.params.id); + next(); + }, + (req, res, next) => { + res.send('User Info'); + } +); + +// handler for the /user/:id path, which prints the user ID +app.get('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +To skip the rest of the middleware functions from a router middleware stack, call `next('route')` to pass control to the next route. + + + +`next('route')` will work only in middleware functions that were loaded by using the +`app.METHOD()` or `router.METHOD()` functions. + + + +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. + +```js +app.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next route + if (req.params.id === '0') next('route'); + // otherwise pass the control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // send a regular response + res.send('regular'); + } +); + +// handler for the /user/:id path, which sends a special response +app.get('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +Middleware can also be declared in an array for reusability. + +This example shows an array with a middleware sub-stack that handles GET requests to the `/user/:id` path + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req.originalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Request Type:', req.method); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app.get('/user/:id', logStuff, (req, res, next) => { + res.send('User Info'); +}); +``` + +## Router-level middleware + +Router-level middleware works in the same way as application-level middleware, except it is bound to an instance of `express.Router()`. + +```js +const router = express.Router(); +``` + +Load router-level middleware by using the `router.use()` and `router.METHOD()` functions. + +The following example code replicates the middleware system that is shown above for application-level middleware, by using router-level middleware: + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// a middleware function with no mount path. This code is executed for every request to the router +router.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); + +// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path +router.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); + +// a middleware sub-stack that handles GET requests to the /user/:id path +router.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next router + if (req.params.id === '0') next('route'); + // otherwise pass control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // render a regular page + res.render('regular'); + } +); + +// handler for the /user/:id path, which renders a special page +router.get('/user/:id', (req, res, next) => { + console.log(req.params.id); + res.render('special'); +}); + +// mount the router on the app +app.use('/', router); +``` + +To skip the rest of the router's middleware functions, call `next('router')` +to pass control back out of the router instance. + +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// predicate the router with a check and bail out when needed +router.use((req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router.get('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// use the router and 401 anything falling through +app.use('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## Error-handling middleware + + + +Error-handling middleware always takes *four* arguments. You must provide four arguments to +identify it as an error-handling middleware function. Even if you don't need to use the `next` +object, you must specify it to maintain the signature. Otherwise, the `next` object will be +interpreted as regular middleware and will fail to handle errors. + + + +Define error-handling middleware functions in the same way as other middleware functions, except with four arguments instead of three, specifically with the signature `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +For details about error-handling middleware, see: [Error handling](/en/guide/error-handling). + +## Built-in middleware + +Starting with version 4.x, Express no longer depends on [Connect](https://github.com/senchalabs/connect). The middleware +functions that were previously included with Express are now in separate modules; see [the list of middleware functions](https://github.com/senchalabs/connect#middleware). + +Express has the following built-in middleware functions: + +* [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. +* [express.json](/en/5x/api#express.json) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** + +## Third-party middleware + +Use third-party middleware to add functionality to Express apps. + +Install the Node.js module for the required functionality, then load it in your app at the application level or at the router level. + +The following example illustrates installing and loading the cookie-parsing middleware function `cookie-parser`. + +```bash +$ npm install cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// load the cookie-parsing middleware +app.use(cookieParser()); +``` + +For a partial list of third-party middleware functions that are commonly used with Express, see: [Third-party middleware](../resources/middleware). diff --git a/src/content/docs/zh-tw/4x/guide/using-template-engines.mdx b/src/content/docs/zh-tw/4x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..7095bc6dd5 --- /dev/null +++ b/src/content/docs/zh-tw/4x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Using template engines with Express +description: Discover how to integrate and use template engines like Pug, Handlebars, and EJS with Express.js to render dynamic HTML pages efficiently. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +A *template engine* enables you to use static template files in your application. At runtime, the template engine replaces +variables in a template file with actual values, and transforms the template into an HTML file sent to the client. +This approach makes it easier to design an HTML page. + +The [Express application generator](/en/starter/generator) uses [Pug](https://pugjs.org/api/getting-started.html) as its default, but it also supports [Handlebars](https://www.npmjs.com/package/handlebars), and [EJS](https://www.npmjs.com/package/ejs), among others. + +To render template files, set the following [application setting properties](/en/4x/api#app.set), in the default `app.js` created by the generator: + +* `views`, the directory where the template files are located. Eg: `app.set('views', './views')`. + This defaults to the `views` directory in the application root directory. +* `view engine`, the template engine to use. For example, to use the Pug template engine: `app.set('view engine', 'pug')`. + +Then install the corresponding template engine npm package; for example to install Pug: + +```bash +$ npm install pug --save +``` + + +Express-compliant template engines such as Pug export a function named `__express(filePath, options, callback)`, +which `res.render()` calls to render the template code. + +Some template engines do not follow this convention. The [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +library follows this convention by mapping all of the popular Node.js template engines, and therefore works seamlessly within Express. + + + +After the view engine is set, you don't have to specify the engine or load the template engine module in your app; +Express loads the module internally, for example: + +```js +app.set('view engine', 'pug'); +``` + +Then, create a Pug template file named `index.pug` in the `views` directory, with the following content: + +```pug +html + head + title= title + body + h1= message +``` + +Create a route to render the `index.pug` file. If the `view engine` property is not set, +you must specify the extension of the `view` file. Otherwise, you can omit it. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +When you make a request to the home page, the `index.pug` file will be rendered as HTML. + +The view engine cache does not cache the contents of the template's output, only the underlying template itself. The view is still re-rendered with every request even when the cache is on. diff --git a/src/content/docs/zh-tw/4x/guide/writing-middleware.mdx b/src/content/docs/zh-tw/4x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..355028e8b0 --- /dev/null +++ b/src/content/docs/zh-tw/4x/guide/writing-middleware.mdx @@ -0,0 +1,239 @@ +--- +title: Writing middleware for use in Express apps +description: Learn how to write custom middleware functions for Express.js applications, including examples and best practices for enhancing request and response handling. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. + +Middleware functions can perform the following tasks: + +* Execute any code. +* Make changes to the request and the response objects. +* End the request-response cycle. +* Call the next middleware in the stack. + +If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. + +The following figure shows the elements of a middleware function call: + +
+ + + + + +
+Elements of a middleware function call + +
HTTP method for which the middleware function applies.
+ +
+ Path (route) for which the middleware function applies. +
+ +
+ The middleware function. +
+ +
+ Callback argument to the middleware function, called "next" by convention. +
+ +
+ HTTP response argument to the middleware function, called "res" by + convention. +
+ +
HTTP request argument to the middleware function, called "req" by convention.
+
+
+ +Starting with Express 5, middleware functions that return a Promise will call `next(value)` when they reject or throw an error. `next` will be called with either the rejected value or the thrown Error. + +## Example + +Here is an example of a simple "Hello World" Express application. +The remainder of this article will define and add three middleware functions to the application: +one called `myLogger` that prints a simple log message, one called `requestTime` that +displays the timestamp of the HTTP request, and one called `validateCookies` that validates incoming cookies. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +### Middleware function myLogger + +Here is a simple example of a middleware function called "myLogger". This function just prints +"LOGGED" when a request to the app passes through it. The middleware function is assigned to a +variable named `myLogger`. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +Notice the call above to `next()`. Calling this function invokes the next middleware function in +the app. The `next()` function is not a part of the Node.js or Express API, but is the third +argument that is passed to the middleware function. The `next()` function could be named anything, +but by convention it is always named "next". To avoid confusion, always use this convention. + + + +To load the middleware function, call `app.use()`, specifying the middleware function. +For example, the following code loads the `myLogger` middleware function before the route to the root path (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +Every time the app receives a request, it prints the message "LOGGED" to the terminal. + +The order of middleware loading is important: middleware functions that are loaded first are also executed first. + +If `myLogger` is loaded after the route to the root path, the request never reaches it and the app doesn't print "LOGGED", because the route handler of the root path terminates the request-response cycle. + +The middleware function `myLogger` simply prints a message, then passes on the request to the next middleware function in the stack by calling the `next()` function. + +### Middleware function requestTime + +Next, we'll create a middleware function called "requestTime" and add a property called `requestTime` +to the request object. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +The app now uses the `requestTime` middleware function. Also, the callback function of the root path route uses the property that the middleware function adds to `req` (the request object). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app.get('/', (req, res) => { + let responseText = 'Hello World!
'; + responseText += `Requested at: ${req.requestTime}`; + res.send(responseText); +}); + +app.listen(3000); +``` + +When you make a request to the root of the app, the app now displays the timestamp of your request in the browser. + +### Middleware function validateCookies + +Finally, we'll create a middleware function that validates incoming cookies and sends a 400 response if cookies are invalid. + +Here's an example function that validates cookies with an external async service. + +```js +async function cookieValidator(cookies) { + try { + await externallyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Invalid cookies'); + } +} +``` + +Here, we use the [`cookie-parser`](/en/resources/middleware/cookie-parser) middleware to parse incoming cookies off the `req` object and pass them to our `cookieValidator` function. The `validateCookies` middleware returns a Promise that upon rejection will automatically trigger our error handler. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('./cookieValidator'); + +const app = express(); + +async function validateCookies(req, res, next) { + await cookieValidator(req.cookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// error handler +app.use((err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Note how `next()` is called after `await cookieValidator(req.cookies)`. This ensures that if +`cookieValidator` resolves, the next middleware in the stack will get called. If you pass anything +to the `next()` function (except the string `'route'` or `'router'`), Express regards the current +request as being an error and will skip any remaining non-error handling routing and middleware +functions. + + + +Because you have access to the request object, the response object, the next middleware function in the stack, and the whole Node.js API, the possibilities with middleware functions are endless. + +For more information about Express middleware, see: [Using Express middleware](/en/guide/using-middleware). + +## Configurable middleware + +If you need your middleware to be configurable, export a function which accepts an options object or other parameters, which, then returns the middleware implementation based on the input parameters. + +File: `my-middleware.js` + +```js +module.exports = function (options) { + return function (req, res, next) { + // Implement the middleware function based on the options object + next(); + }; +}; +``` + +The middleware can now be used as shown below. + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Refer to [cookie-session](https://github.com/expressjs/cookie-session) and [compression](https://github.com/expressjs/compression) for examples of configurable middleware. diff --git a/src/content/docs/zh-tw/4x/starter/basic-routing.mdx b/src/content/docs/zh-tw/4x/starter/basic-routing.mdx new file mode 100644 index 0000000000..35d674808b --- /dev/null +++ b/src/content/docs/zh-tw/4x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Basic routing +description: Learn the fundamentals of routing in Express.js applications, including how to define routes, handle HTTP methods, and create route handlers for your web server. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). + +Each route can have one or more handler functions, which are executed when the route is matched. + +Route definition takes the following structure: + +```js +app.METHOD(PATH, HANDLER); +``` + +Where: + +* `app` is an instance of `express`. +* `METHOD` is an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in lowercase. +* `PATH` is a path on the server. +* `HANDLER` is the function executed when the route is matched. + + + +This tutorial assumes that an instance of `express` named `app` is created and the server is +running. If you are not familiar with creating an app and starting it, see the Hello world +example. + + + +The following examples illustrate defining simple routes. + +Respond with `Hello World!` on the homepage: + +```js +app.get('/', (req, res) => { + res.send('Hello World!'); +}); +``` + +Respond to a POST request on the root route (`/`), the application's home page: + +```js +app.post('/', (req, res) => { + res.send('Got a POST request'); +}); +``` + +Respond to a PUT request to the `/user` route: + +```js +app.put('/user', (req, res) => { + res.send('Got a PUT request at /user'); +}); +``` + +Respond to a DELETE request to the `/user` route: + +```js +app.delete('/user', (req, res) => { + res.send('Got a DELETE request at /user'); +}); +``` + +For more details about routing, see the [routing guide](/en/guide/routing). diff --git a/src/content/docs/zh-tw/4x/starter/examples.mdx b/src/content/docs/zh-tw/4x/starter/examples.mdx new file mode 100644 index 0000000000..4135b751cd --- /dev/null +++ b/src/content/docs/zh-tw/4x/starter/examples.mdx @@ -0,0 +1,45 @@ +--- +title: Express examples +description: Explore a collection of Express.js application examples covering various use cases, integrations, and advanced configurations to help you learn and build your projects. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Authentication with login and password +* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - HTTP content negotiation +* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Working with cookie-based sessions +* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Working with cookies +* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transferring files to client +* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Working with Embedded JavaScript templating (ejs) +* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Creating error pages +* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Working with error middleware +* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Simple request handler +* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown as template engine +* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Working with multiple Express routers +* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - MVC-style controllers +* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Tracking online user activity with `online` and `redis` packages +* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Working with route parameters +* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Multiple HTTP operations on the same resource +* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organizing routes using a map +* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Working with route middleware +* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizing routes per each resource +* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Search API +* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - User sessions +* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Serving static files +* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Working with virtual hosts +* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Rendering views dynamically +* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Saving data in request object between middleware calls +* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Simple API service + +## Additional examples + +These are some additional examples with more extensive integrations. + + + This information refers to third-party sites, products, or modules that are not maintained by the + Expressjs team. Listing here does not constitute an endorsement or recommendation from the + Expressjs project team. + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app with Express and Next.js using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM diff --git a/src/content/docs/zh-tw/4x/starter/faq.md b/src/content/docs/zh-tw/4x/starter/faq.md new file mode 100644 index 0000000000..1adcb7be0e --- /dev/null +++ b/src/content/docs/zh-tw/4x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: FAQ +description: Find answers to frequently asked questions about Express.js, including topics on application structure, models, authentication, template engines, error handling, and more. +--- + +## How should I structure my application? + +There is no definitive answer to this question. The answer depends +on the scale of your application and the team that is involved. To be as +flexible as possible, Express makes no assumptions in terms of structure. + +Routes and other application-specific logic can live in as many files +as you wish, in any directory structure you prefer. View the following +examples for inspiration: + +- [Route listings](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Route map](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Also, there are third-party extensions for Express, which simplify some of these patterns: + +- [Resourceful routing](https://github.com/expressjs/express-resource) + +## How do I define models? + +Express has no notion of a database. This concept is +left up to third-party Node modules, allowing you to +interface with nearly any database. + +See [LoopBack](http://loopback.io) for an Express-based framework that is centered around models. + +## How can I authenticate users? + +Authentication is another opinionated area that Express does not +venture into. You may use any authentication scheme you wish. +For a simple username / password scheme, see [this example](https://github.com/expressjs/express/tree/master/examples/auth). + +## Which template engines does Express support? + +Express supports any template engine that conforms with the `(path, locals, callback)` signature. +To normalize template engine interfaces and caching, see the +[consolidate.js](https://github.com/visionmedia/consolidate.js) +project for support. Unlisted template engines might still support the Express signature. + +For more information, see [Using template engines with Express](/en/guide/using-template-engines). + +## How do I handle 404 responses? + +In Express, 404 responses are not the result of an error, so +the error-handler middleware will not capture them. This behavior is +because a 404 response simply indicates the absence of additional work to do; +in other words, Express has executed all middleware functions and routes, +and found that none of them responded. All you need to +do is add a middleware function at the very bottom of the stack (below all other functions) +to handle a 404 response: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Add routes dynamically at runtime on an instance of `express.Router()` +so the routes are not superseded by a middleware function. + +## How do I setup an error handler? + +You define error-handling middleware in the same way as other middleware, +except with four arguments instead of three; specifically with the signature `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +For more information, see [Error handling](/en/guide/error-handling). + +## How do I render plain HTML? + +You don't! There's no need to "render" HTML with the `res.render()` function. +If you have a specific file, use the `res.sendFile()` function. +If you are serving many assets from a directory, use the `express.static()` +middleware function. + +## What version of Node.js does Express require? + +- [Express 4.x](/en/4x/api) requires Node.js 0.10 or higher. +- [Express 5.x](/en/5x/api) requires Node.js 18 or higher. diff --git a/src/content/docs/zh-tw/4x/starter/generator.mdx b/src/content/docs/zh-tw/4x/starter/generator.mdx new file mode 100644 index 0000000000..859bec927e --- /dev/null +++ b/src/content/docs/zh-tw/4x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Express application generator +description: Learn how to use the Express application generator tool to quickly create a skeleton for your Express.js applications, streamlining setup and configuration. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Use the application generator tool, `express-generator`, to quickly create an application skeleton. + +You can run the application generator with the `npx` command (available in Node.js 8.2.0). + +```bash +$ npx express-generator +``` + +For earlier Node versions, install the application generator as a global npm package and then launch it: + +```bash +$ npm install -g express-generator +$ express +``` + +Display the command options with the `-h` option: + +```bash +$ express -h + + Usage: express [options] [dir] + + Options: + + -h, --help output usage information + --version output the version number + -e, --ejs add ejs engine support + --hbs add handlebars engine support + --pug add pug engine support + -H, --hogan add hogan.js engine support + --no-view generate without view engine + -v, --view add view support (ejs|hbs|hjs|jade|pug|twig|vash) (defaults to jade) + -c, --css add stylesheet support (less|stylus|compass|sass) (defaults to plain css) + --git add .gitignore + -f, --force force on non-empty directory +``` + +For example, the following creates an Express app named *myapp*. The app will be created in a folder named *myapp* in the current working directory and the view engine will be set to Pug: + +```bash +$ express --view=pug myapp + + create : myapp + create : myapp/package.json + create : myapp/app.js + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index.js + create : myapp/routes/users.js + create : myapp/public/stylesheets + create : myapp/public/stylesheets/style.css + create : myapp/views + create : myapp/views/index.pug + create : myapp/views/layout.pug + create : myapp/views/error.pug + create : myapp/bin + create : myapp/bin/www +``` + +Then install dependencies: + +```bash +$ cd myapp +$ npm install +``` + +On MacOS or Linux, run the app with this command: + +```bash +$ DEBUG=myapp:* npm start +``` + +On Windows Command Prompt, use this command: + +```bash +> set DEBUG=myapp:* & npm start +``` + +On Windows PowerShell, use this command: + +```bash +PS> $env:DEBUG='myapp:*'; npm start +``` + +Then, load `http://localhost:3000/` in your browser to access the app. + +The generated app has the following directory structure: + +```bash +. +├── app.js +├── bin +│ └── www +├── package.json +├── public +│ ├── images +│ ├── javascripts +│ └── stylesheets +│ └── style.css +├── routes +│ ├── index.js +│ └── users.js +└── views + ├── error.pug + ├── index.pug + └── layout.pug + +7 directories, 9 files +``` + + + +The app structure created by the generator is just one of many ways to structure Express apps. +Feel free to use this structure or modify it to best suit your needs. + + diff --git a/src/content/docs/zh-tw/4x/starter/hello-world.mdx b/src/content/docs/zh-tw/4x/starter/hello-world.mdx new file mode 100644 index 0000000000..d92beecd0a --- /dev/null +++ b/src/content/docs/zh-tw/4x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Hello world example +description: Get started with Express.js by building a simple 'Hello World' application, demonstrating the basic setup and server creation for beginners. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Embedded below is essentially the simplest Express app you can create. It is a single file app +— *not* what you'd get if you use the [Express generator](/en/starter/generator), which +creates the scaffolding for a full app with numerous JavaScript files, Jade templates, and +sub-directories for various purposes. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(port, () => { + console.log(`Example app listening on port ${port}`); +}); +``` + +This app starts a server and listens on port 3000 for connections. The app responds with "Hello World!" for requests +to the root URL (`/`) or *route*. For every other path, it will respond with a **404 Not Found**. + +## Running Locally + +First create a directory named `myapp`, change to it and run `npm init`. Then, install `express` as a dependency, as per the [installation guide](/en/starter/installing). + +In the `myapp` directory, create a file named `app.js` and copy the code from the example above. + + + +The `req` (request) and `res` (response) are the exact same objects that Node provides, so you can +invoke `req.pipe()`, `req.on('data', callback)`, and anything else you would do without Express +involved. + + + +Run the app with the following command: + +```bash +$ node app.js +``` + +Then, load `http://localhost:3000/` in a browser to see the output. diff --git a/src/content/docs/zh-tw/4x/starter/installing.mdx b/src/content/docs/zh-tw/4x/starter/installing.mdx new file mode 100644 index 0000000000..fc66c7f9df --- /dev/null +++ b/src/content/docs/zh-tw/4x/starter/installing.mdx @@ -0,0 +1,50 @@ +--- +title: Installing +description: Learn how to install Express.js in your Node.js environment, including setting up your project directory and managing dependencies with npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Before you begin, make sure you have [Node.js](https://nodejs.org/) 0.10 or higher installed. Then, create a directory for your application and navigate into it. + +```bash +mkdir myapp +cd myapp +``` + +Use the `npm init` command to create a `package.json` file for your application. +For more information on how `package.json` works, see [Specifics of npm's package.json handling](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +This command prompts you for a number of things, such as the name and version of your application. +For now, you can simply hit RETURN to accept the defaults for most of them, with the following exception: + +``` +entry point: (index.js) +``` + +Enter `app.js`, or whatever you want the name of the main file to be. If you want it to be `index.js`, hit RETURN to accept the suggested default file name. + +Now, install Express in the `myapp` directory and save it in the dependencies list. For example: + +```bash +npm install express +``` + +To install Express temporarily and not add it to the dependencies list: + +```bash +npm install express --no-save +``` + + + +By default with version npm 5.0+, `npm install` adds the module to the `dependencies` list in the +`package.json` file; with earlier versions of npm, you must specify the `--save` option +explicitly. Then, afterwards, running `npm install` in the app directory will automatically +install modules in the dependencies list. + + diff --git a/src/content/docs/zh-tw/4x/starter/static-files.mdx b/src/content/docs/zh-tw/4x/starter/static-files.mdx new file mode 100644 index 0000000000..98855e0d05 --- /dev/null +++ b/src/content/docs/zh-tw/4x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Serving static files in Express +description: Understand how to serve static files like images, CSS, and JavaScript in Express.js applications using the built-in 'static' middleware. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +To serve static files such as images, CSS files, and JavaScript files, use the `express.static` built-in middleware function in Express. + +The function signature is: + +```js +express.static(root, [options]); +``` + +The `root` argument specifies the root directory from which to serve static assets. +For more information on the `options` argument, see [express.static](/en/5x/api#express.static). + +For example, use the following code to serve images, CSS files, and JavaScript files in a directory named `public`: + +```js +app.use(express.static('public')); +``` + +Now, you can load the files that are in the `public` directory: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express looks up the files relative to the static directory, so the name of the static directory +is not part of the URL. + + + +To use multiple static assets directories, call the `express.static` middleware function multiple times: + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express looks up the files in the order in which you set the static directories with the `express.static` middleware function. + + + +For best results, use a reverse +proxy cache to improve performance of +serving static assets. + + + +To create a virtual path prefix (where the path does not actually exist in the file system) for files that are served by the `express.static` function, [specify a mount path](/en/5x/api#app.use) for the static directory, as shown below: + +```js +app.use('/static', express.static('public')); +``` + +Now, you can load the files that are in the `public` directory from the `/static` path prefix. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +However, the path that you provide to the `express.static` function is relative to the directory from where you launch your `node` process. If you run the express app from another directory, it's safer to use the absolute path of the directory that you want to serve: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public'))); +``` + +For more details about the `serve-static` function and its options, see [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/docs/zh-tw/5x/advanced/developing-template-engines.md b/src/content/docs/zh-tw/5x/advanced/developing-template-engines.md new file mode 100644 index 0000000000..6e9710fbc5 --- /dev/null +++ b/src/content/docs/zh-tw/5x/advanced/developing-template-engines.md @@ -0,0 +1,43 @@ +--- +title: Developing template engines for Express +description: Learn how to develop custom template engines for Express.js using app.engine(), with examples on creating and integrating your own template rendering logic. +--- + +Use the `app.engine(ext, callback)` method to create your own template engine. `ext` refers to the file extension, and `callback` is the template engine function, which accepts the following items as parameters: the location of the file, the options object, and the callback function. + +The following code is an example of implementing a very simple template engine for rendering `.ntl` files. + +```js +const fs = require('fs'); // this engine requires the fs module +app.engine('ntl', (filePath, options, callback) => { + // define the template engine + fs.readFile(filePath, (err, content) => { + if (err) return callback(err); + // this is an extremely simple template engine + const rendered = content + .toString() + .replace('#title#', `${options.title}`) + .replace('#message#', `

${options.message}

`); + return callback(null, rendered); + }); +}); +app.set('views', './views'); // specify the views directory +app.set('view engine', 'ntl'); // register the template engine +``` + +Your app will now be able to render `.ntl` files. Create a file named `index.ntl` in the `views` directory with the following content. + +```pug +#title# +#message# +``` + +Then, create the following route in your app. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +When you make a request to the home page, `index.ntl` will be rendered as HTML. diff --git a/src/content/docs/zh-tw/5x/guide/behind-proxies.mdx b/src/content/docs/zh-tw/5x/guide/behind-proxies.mdx new file mode 100644 index 0000000000..dc509998f7 --- /dev/null +++ b/src/content/docs/zh-tw/5x/guide/behind-proxies.mdx @@ -0,0 +1,102 @@ +--- +title: Express behind proxies +description: Learn how to configure Express.js applications to work correctly behind reverse proxies, including using the trust proxy setting to handle client IP addresses. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +When running an Express app behind a reverse proxy, some of the Express APIs may return different values than expected. In order to adjust for this, the `trust proxy` application setting may be used to expose information provided by the reverse proxy in the Express APIs. The most common issue is express APIs that expose the client's IP address may instead show an internal IP address of the reverse proxy. + + + +When configuring the `trust proxy` setting, it is important to understand the exact setup of the +reverse proxy. Since this setting will trust values provided in the request, it is important that +the combination of the setting in Express matches how the reverse proxy operates. + + + +The application setting `trust proxy` may be set to one of the values listed in the following table. + + + + + + + + + + + + + + + + + + + + + +
TypeValue
Boolean +If `true`, the client's IP address is understood as the left-most entry in the `X-Forwarded-For` header. + +If `false`, the app is understood as directly facing the client and the client's IP address is derived from `req.socket.remoteAddress`. This is the default setting. + + +When setting to `true`, it is important to ensure that the last reverse proxy trusted is removing/overwriting all of the following HTTP headers: `X-Forwarded-For`, `X-Forwarded-Host`, and `X-Forwarded-Proto`, otherwise it may be possible for the client to provide any value. + +
IP addresses +An IP address, subnet, or an array of IP addresses and subnets to trust as being a reverse proxy. The following list shows the pre-configured subnet names: + +* loopback - `127.0.0.1/8`, `::1/128` +* linklocal - `169.254.0.0/16`, `fe80::/10` +* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` + +You can set IP addresses in any of the following ways: + +```js +app.set('trust proxy', 'loopback'); // specify a single subnet +app.set('trust proxy', 'loopback, 123.123.123.123'); // specify a subnet and an address +app.set('trust proxy', 'loopback, linklocal, uniquelocal'); // specify multiple subnets as CSV +app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // specify multiple subnets as an array +``` + +When specified, the IP addresses or the subnets are excluded from the address determination process, and the untrusted IP address nearest to the application server is determined as the client's IP address. This works by checking if `req.socket.remoteAddress` is trusted. If so, then each address in `X-Forwarded-For` is checked from right to left until the first non-trusted address. + +
Number +Use the address that is at most `n` number of hops away from the Express application. `req.socket.remoteAddress` is the first hop, and the rest are looked for in the `X-Forwarded-For` header from right to left. A value of `0` means that the first untrusted address would be `req.socket.remoteAddress`, i.e. there is no reverse proxy. + + +When using this setting, it is important to ensure there are not multiple, different-length paths to the Express application such that the client can be less than the configured number of hops away, otherwise it may be possible for the client to provide any value. + +
Function +Custom trust implementation. + +```js +app.set('trust proxy', (ip) => { + if (ip === '127.0.0.1' || ip === '123.123.123.123') + return true; // trusted IPs + else return false; +}); +``` + +
+ +Enabling `trust proxy` will have the following impact: + +
    +
  • + The value of [req.hostname](/en/api#req.hostname) is derived from the value set in the + `X-Forwarded-Host` header, which can be set by the client or by the proxy. +
    • +
  • + `X-Forwarded-Proto` can be set by the reverse proxy to tell the app whether it is `https` or + `http` or even an invalid name. This value is reflected by [req.protocol](/en/api#req.protocol). +
    • +
  • + The [req.ip](/en/api#req.ip) and [req.ips](/en/api#req.ips) values are populated based on the + socket address and `X-Forwarded-For` header, starting at the first untrusted address. +
    • +
+ +The `trust proxy` setting is implemented using the [proxy-addr](https://www.npmjs.com/package/proxy-addr) package. For more information, see its documentation. diff --git a/src/content/docs/zh-tw/5x/guide/debugging.mdx b/src/content/docs/zh-tw/5x/guide/debugging.mdx new file mode 100644 index 0000000000..a7750f5427 --- /dev/null +++ b/src/content/docs/zh-tw/5x/guide/debugging.mdx @@ -0,0 +1,124 @@ +--- +title: Debugging Express +description: Learn how to enable and use debugging logs in Express.js applications by setting the DEBUG environment variable for enhanced troubleshooting. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +To see all the internal logs used in Express, set the `DEBUG` environment variable to +`express:*` when launching your app. + +```bash +$ DEBUG=express:* node index.js +``` + +On Windows, use the corresponding command. + +```bash +> $env:DEBUG = "express:*"; node index.js +``` + +Running this command on the default app generated by the [express generator](/en/starter/generator) prints the following output: + +```bash +$ DEBUG=express:* node ./bin/www + express:router:route new / +0ms + express:router:layer new / +1ms + express:router:route get / +1ms + express:router:layer new / +0ms + express:router:route new / +1ms + express:router:layer new / +0ms + express:router:route get / +0ms + express:router:layer new / +0ms + express:application compile etag weak +1ms + express:application compile query parser extended +0ms + express:application compile trust proxy false +0ms + express:application booting in development mode +1ms + express:router use / query +0ms + express:router:layer new / +0ms + express:router use / expressInit +0ms + express:router:layer new / +0ms + express:router use / favicon +1ms + express:router:layer new / +0ms + express:router use / logger +0ms + express:router:layer new / +0ms + express:router use / jsonParser +0ms + express:router:layer new / +1ms + express:router use / urlencodedParser +0ms + express:router:layer new / +0ms + express:router use / cookieParser +0ms + express:router:layer new / +0ms + express:router use / stylus +90ms + express:router:layer new / +0ms + express:router use / serveStatic +0ms + express:router:layer new / +0ms + express:router use / router +0ms + express:router:layer new / +1ms + express:router use /users router +0ms + express:router:layer new /users +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms + express:router use / <anonymous> +0ms + express:router:layer new / +0ms +``` + +When a request is then made to the app, you will see the logs specified in the Express code: + +```bash + express:router dispatching GET / +4h + express:router query : / +2ms + express:router expressInit : / +0ms + express:router favicon : / +0ms + express:router logger : / +1ms + express:router jsonParser : / +0ms + express:router urlencodedParser : / +1ms + express:router cookieParser : / +0ms + express:router stylus : / +0ms + express:router serveStatic : / +2ms + express:router router : / +2ms + express:router dispatching GET / +1ms + express:view lookup "index.pug" +338ms + express:view stat "/projects/example/views/index.pug" +0ms + express:view render "/projects/example/views/index.pug" +1ms +``` + +To see the logs only from the router implementation, set the value of `DEBUG` to `express:router`. Likewise, to see logs only from the application implementation, set the value of `DEBUG` to `express:application`, and so on. + +## Applications generated by `express` + +An application generated by the `express` command uses the `debug` module and its debug namespace is scoped to the name of the application. + +For example, if you generated the app with `$ express sample-app`, you can enable the debug statements with the following command: + +```bash +$ DEBUG=sample-app:* node ./bin/www +``` + +You can specify more than one debug namespace by assigning a comma-separated list of names: + +```bash +$ DEBUG=http,mail,express:* node index.js +``` + +## Advanced options + +When running through Node.js, you can set a few environment variables that will change the behavior of the debug logging: + +| Name | Purpose | +| ------------------- | ------------------------------------------------- | +| `DEBUG` | Enables/disables specific debugging namespaces. | +| `DEBUG_COLORS` | Whether or not to use colors in the debug output. | +| `DEBUG_DEPTH` | Object inspection depth. | +| `DEBUG_FD` | File descriptor to write debug output to. | +| `DEBUG_SHOW_HIDDEN` | Shows hidden properties on inspected objects. | + + + +The environment variables beginning with `DEBUG_` end up being converted into an Options object +that gets used with `%o`/`%O` formatters. See the Node.js documentation for +[`util.inspect()`](https://nodejs.org/api/util#util_util_inspect_object_options) for the complete +list. + + diff --git a/src/content/docs/zh-tw/5x/guide/error-handling.mdx b/src/content/docs/zh-tw/5x/guide/error-handling.mdx new file mode 100644 index 0000000000..78f1c86e92 --- /dev/null +++ b/src/content/docs/zh-tw/5x/guide/error-handling.mdx @@ -0,0 +1,312 @@ +--- +title: Error Handling +description: Understand how Express.js handles errors in synchronous and asynchronous code, and learn to implement custom error handling middleware for your applications. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Error Handling* refers to how Express catches and processes errors that +occur both synchronously and asynchronously. Express comes with a default error +handler so you don't need to write your own to get started. + +## Catching Errors + +It's important to ensure that Express catches all errors that occur while +running route handlers and middleware. + +Errors that occur in synchronous code inside route handlers and middleware +require no extra work. If synchronous code throws an error, then Express will +catch and process it. For example: + +```js +app.get('/', (req, res) => { + throw new Error('BROKEN'); // Express will catch this on its own. +}); +``` + +For errors returned from asynchronous functions invoked by route handlers +and middleware, you must pass them to the `next()` function, where Express will +catch and process them. For example: + +```js +app.get('/', (req, res, next) => { + fs.readFile('/file-does-not-exist', (err, data) => { + if (err) { + next(err); // Pass errors to Express. + } else { + res.send(data); + } + }); +}); +``` + +Starting with Express 5, route handlers and middleware that return a Promise +will call `next(value)` automatically when they reject or throw an error. +For example: + +```js +app.get('/user/:id', async (req, res, next) => { + const user = await getUserById(req.params.id); + res.send(user); +}); +``` + +If `getUserById` throws an error or rejects, `next` will be called with either +the thrown error or the rejected value. If no rejected value is provided, `next` +will be called with a default Error object provided by the Express router. + +If you pass anything to the `next()` function (except the string `'route'`), +Express regards the current request as being an error and will skip any +remaining non-error handling routing and middleware functions. + +If the callback in a sequence provides no data, only errors, you can simplify +this code as follows: + +```js +app.get('/', [ + function (req, res, next) { + fs.writeFile('/inaccessible-path', 'data', next); + }, + function (req, res) { + res.send('OK'); + }, +]); +``` + +In the above example, `next` is provided as the callback for `fs.writeFile`, +which is called with or without errors. If there is no error, the second +handler is executed, otherwise Express catches and processes the error. + +You must catch errors that occur in asynchronous code invoked by route handlers or +middleware and pass them to Express for processing. For example: + +```js +app.get('/', (req, res, next) => { + setTimeout(() => { + try { + throw new Error('BROKEN'); + } catch (err) { + next(err); + } + }, 100); +}); +``` + +The above example uses a `try...catch` block to catch errors in the +asynchronous code and pass them to Express. If the `try...catch` +block were omitted, Express would not catch the error since it is not part of the synchronous +handler code. + +Use promises to avoid the overhead of the `try...catch` block or when using functions +that return promises. For example: + +```js +app.get('/', (req, res, next) => { + Promise.resolve() + .then(() => { + throw new Error('BROKEN'); + }) + .catch(next); // Errors will be passed to Express. +}); +``` + +Since promises automatically catch both synchronous errors and rejected promises, +you can simply provide `next` as the final catch handler and Express will catch errors, +because the catch handler is given the error as the first argument. + +You could also use a chain of handlers to rely on synchronous error +catching, by reducing the asynchronous code to something trivial. For example: + +```js +app.get('/', [ + function (req, res, next) { + fs.readFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals.data = data; + next(err); + }); + }, + function (req, res) { + res.locals.data = res.locals.data.split(',')[1]; + res.send(res.locals.data); + }, +]); +``` + +The above example has a couple of trivial statements from the `readFile` +call. If `readFile` causes an error, then it passes the error to Express, otherwise you +quickly return to the world of synchronous error handling in the next handler +in the chain. Then, the example above tries to process the data. If this fails, then the +synchronous error handler will catch it. If you had done this processing inside +the `readFile` callback, then the application might exit and the Express error +handlers would not run. + +Whichever method you use, if you want Express error handlers to be called in and the +application to survive, you must ensure that Express receives the error. + +## The default error handler + +Express comes with a built-in error handler that takes care of any errors that might be encountered in the app. This default error-handling middleware function is added at the end of the middleware function stack. + +If you pass an error to `next()` and you do not handle it in a custom error +handler, it will be handled by the built-in error handler; the error will be +written to the client with the stack trace. The stack trace is not included +in the production environment. + + + +Set the environment variable `NODE_ENV` to `production`, to run the app in production mode. + + + +When an error is written, the following information is added to the +response: + +* The `res.statusCode` is set from `err.status` (or `err.statusCode`). If + this value is outside the 4xx or 5xx range, it will be set to 500. +* The `res.statusMessage` is set according to the status code. +* The body will be the HTML of the status code message when in production + environment, otherwise will be `err.stack`. +* Any headers specified in an `err.headers` object. + +If you call `next()` with an error after you have started writing the +response (for example, if you encounter an error while streaming the +response to the client), the Express default error handler closes the +connection and fails the request. + +So when you add a custom error handler, you must delegate to +the default Express error handler, when the headers +have already been sent to the client: + +```js +function errorHandler(err, req, res, next) { + if (res.headersSent) { + return next(err); + } + res.status(500); + res.render('error', { error: err }); +} +``` + +Note that the default error handler can get triggered if you call `next()` with an error +in your code more than once, even if custom error handling middleware is in place. + +Other error handling middleware can be found at [Express middleware](/en/resources/middleware). + +## Writing error handlers + +Define error-handling middleware functions in the same way as other middleware functions, +except error-handling functions have four arguments instead of three: +`(err, req, res, next)`. For example: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +You define error-handling middleware last, after other `app.use()` and routes calls; for example: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser.urlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app.use(methodOverride()); +app.use((err, req, res, next) => { + // logic +}); +``` + +Responses from within a middleware function can be in any format, such as an HTML error page, a simple message, or a JSON string. + +For organizational (and higher-level framework) purposes, you can define +several error-handling middleware functions, much as you would with +regular middleware functions. For example, to define an error-handler +for requests made by using `XHR` and those without: + +```js +const bodyParser = require('body-parser'); +const methodOverride = require('method-override'); + +app.use( + bodyParser.urlencoded({ + extended: true, + }) +); +app.use(bodyParser.json()); +app.use(methodOverride()); +app.use(logErrors); +app.use(clientErrorHandler); +app.use(errorHandler); +``` + +In this example, the generic `logErrors` might write request and +error information to `stderr`, for example: + +```js +function logErrors(err, req, res, next) { + console.error(err.stack); + next(err); +} +``` + +Also in this example, `clientErrorHandler` is defined as follows; in this case, the error is explicitly passed along to the next one. + +Notice that when *not* calling "next" in an error-handling function, you are responsible for writing (and ending) the response. Otherwise, those requests will "hang" and will not be eligible for garbage collection. + +```js +function clientErrorHandler(err, req, res, next) { + if (req.xhr) { + res.status(500).send({ error: 'Something failed!' }); + } else { + next(err); + } +} +``` + +Implement the "catch-all" `errorHandler` function as follows (for example): + +```js +function errorHandler(err, req, res, next) { + res.status(500); + res.render('error', { error: err }); +} +``` + +If you have a route handler with multiple callback functions, you can use the `route` parameter to skip to the next route handler. For example: + +```js +app.get( + '/a_route_behind_paywall', + (req, res, next) => { + if (!req.user.hasPaid) { + // continue handling this request + next('route'); + } else { + next(); + } + }, + (req, res, next) => { + PaidContent.find((err, doc) => { + if (err) return next(err); + res.json(doc); + }); + } +); +``` + +In this example, the `getPaidContent` handler will be skipped but any remaining handlers in `app` for `/a_route_behind_paywall` would continue to be executed. + + + +Calls to `next()` and `next(err)` indicate that the current handler is complete and in what state. +`next(err)` will skip all remaining handlers in the chain except for those that are set up to +handle errors as described above. + + diff --git a/src/content/docs/zh-tw/5x/guide/overriding-express-api.md b/src/content/docs/zh-tw/5x/guide/overriding-express-api.md new file mode 100644 index 0000000000..f5281a58f5 --- /dev/null +++ b/src/content/docs/zh-tw/5x/guide/overriding-express-api.md @@ -0,0 +1,68 @@ +--- +title: Overriding the Express API +description: Discover how to customize and extend the Express.js API by overriding methods and properties on the request and response objects using prototypes. +--- + +The Express API consists of various methods and properties on the request and response objects. These are inherited by prototype. There are two extension points for the Express API: + +1. The global prototypes at `express.request` and `express.response`. +2. App-specific prototypes at `app.request` and `app.response`. + +Altering the global prototypes will affect all loaded Express apps in the same process. If desired, alterations can be made app-specific by only altering the app-specific prototypes after creating a new app. + +## Methods + +You can override the signature and behavior of existing methods with your own, by assigning a custom function. + +Following is an example of overriding the behavior of [res.sendStatus](/en/4x/api#res.sendStatus). + +```js +app.response.sendStatus = function (statusCode, type, message) { + // code is intentionally kept simple for demonstration purpose + return this.contentType(type).status(statusCode).send(message); +}; +``` + +The above implementation completely changes the original signature of `res.sendStatus`. It now accepts a status code, encoding type, and the message to be sent to the client. + +The overridden method may now be used this way: + +```js +res.sendStatus(404, 'application/json', '{"error":"resource not found"}'); +``` + +## Properties + +Properties in the Express API are either: + +1. Assigned properties (ex: `req.baseUrl`, `req.originalUrl`) +2. Defined as getters (ex: `req.secure`, `req.ip`) + +Since properties under category 1 are dynamically assigned on the `request` and `response` objects in the context of the current request-response cycle, their behavior cannot be overridden. + +Properties under category 2 can be overwritten using the Express API extensions API. + +The following code rewrites how the value of `req.ip` is to be derived. Now, it simply returns the value of the `Client-IP` request header. + +```js +Object.defineProperty(app.request, 'ip', { + configurable: true, + enumerable: true, + get() { + return this.get('Client-IP'); + }, +}); +``` + +## Prototype + +In order to provide the Express API, the request/response objects passed to Express (via `app(req, res)`, for example) need to inherit from the same prototype chain. By default, this is `http.IncomingRequest.prototype` for the request and `http.ServerResponse.prototype` for the response. + +Unless necessary, it is recommended that this be done only at the application level, rather than globally. Also, take care that the prototype that is being used matches the functionality as closely as possible to the default prototypes. + +```js +// Use FakeRequest and FakeResponse in place of http.IncomingRequest and http.ServerResponse +// for the given app reference +Object.setPrototypeOf(Object.getPrototypeOf(app.request), FakeRequest.prototype); +Object.setPrototypeOf(Object.getPrototypeOf(app.response), FakeResponse.prototype); +``` diff --git a/src/content/docs/zh-tw/5x/guide/routing.mdx b/src/content/docs/zh-tw/5x/guide/routing.mdx new file mode 100644 index 0000000000..78ab64f6e8 --- /dev/null +++ b/src/content/docs/zh-tw/5x/guide/routing.mdx @@ -0,0 +1,418 @@ +--- +title: Routing +description: Learn how to define and use routes in Express.js applications, including route methods, route paths, parameters, and using Router for modular routing. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* refers to how an application's endpoints (URIs) respond to client requests. +For an introduction to routing, see [Basic routing](/en/starter/basic-routing). + +You define routing using methods of the Express `app` object that correspond to HTTP methods; +for example, `app.get()` to handle GET requests and `app.post` to handle POST requests. For a full list, +see [app.METHOD](/en/5x/api#app.METHOD). You can also use [app.all()](/en/5x/api#app.all) to handle all HTTP methods and [app.use()](/en/5x/api#app.use) to +specify middleware as the callback function (See [Using middleware](/en/guide/using-middleware) for details). + +These routing methods specify a callback function (sometimes called "handler functions") called when the application receives a request to the specified route (endpoint) and HTTP method. In other words, the application "listens" for requests that match the specified route(s) and method(s), and when it detects a match, it calls the specified callback function. + +In fact, the routing methods can have more than one callback function as arguments. +With multiple callback functions, it is important to provide `next` as an argument to the callback function and then call `next()` within the body of the function to hand off control +to the next callback. + +The following code is an example of a very basic route. + +```js +const express = require('express'); +const app = express(); + +// respond with "hello world" when a GET request is made to the homepage +app.get('/', (req, res) => { + res.send('hello world'); +}); +``` + +## Route methods + +A route method is derived from one of the HTTP methods, and is attached to an instance of the `express` class. + +The following code is an example of routes that are defined for the `GET` and the `POST` methods to the root of the app. + +```js +// GET method route +app.get('/', (req, res) => { + res.send('GET request to the homepage'); +}); + +// POST method route +app.post('/', (req, res) => { + res.send('POST request to the homepage'); +}); +``` + +Express supports methods that correspond to all HTTP request methods: `get`, `post`, and so on. +For a full list, see [app.METHOD](/en/5x/api#app.METHOD). + +There is a special routing method, `app.all()`, used to load middleware functions at a path for *all* HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). + +```js +app.all('/secret', (req, res, next) => { + console.log('Accessing the secret section ...'); + next(); // pass control to the next handler +}); +``` + +## Route paths + +Route paths, in combination with a request method, define the endpoints at which requests can be made. Route paths can be strings, string patterns, or regular expressions. + + + +In express 5, the characters `?`, `+`, `*`, `[]`, and `()` are handled differently than in version +4, please review the [migration guide](/en/guide/migrating-5#path-syntax) for more information. + + + + + +In express 4, regular expression characters such as `$` need to be escaped with a `\`. + + + + + +Express uses [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) for matching the route +paths; see the path-to-regexp documentation for all the possibilities in defining route paths. +[Express Playground Router](https://bjohansebas.github.io/playground-router/) is a handy tool for +testing basic Express routes, although it does not support pattern matching. + + + +Query strings are not part of the route path. + +### Route paths based on strings + +This route path will match requests to the root route, `/`. + +```js +app.get('/', (req, res) => { + res.send('root'); +}); +``` + +This route path will match requests to `/about`. + +```js +app.get('/about', (req, res) => { + res.send('about'); +}); +``` + +This route path will match requests to `/random.text`. + +```js +app.get('/random.text', (req, res) => { + res.send('random.text'); +}); +``` + +### Route paths based on string patterns + + + +The string patterns in Express 5 no longer work. Please refer to the migration +guide for more information. + + + +This route path will match `acd` and `abcd`. + +```js +app.get('/ab?cd', (req, res) => { + res.send('ab?cd'); +}); +``` + +This route path will match `abcd`, `abbcd`, `abbbcd`, and so on. + +```js +app.get('/ab+cd', (req, res) => { + res.send('ab+cd'); +}); +``` + +This route path will match `abcd`, `abxcd`, `abRANDOMcd`, `ab123cd`, and so on. + +```js +app.get('/ab*cd', (req, res) => { + res.send('ab*cd'); +}); +``` + +This route path will match `/abe` and `/abcde`. + +```js +app.get('/ab(cd)?e', (req, res) => { + res.send('ab(cd)?e'); +}); +``` + +### Route paths based on regular expressions + +This route path will match anything with an "a" in it. + +```js +app.get(/a/, (req, res) => { + res.send('/a/'); +}); +``` + +This route path will match `butterfly` and `dragonfly`, but not `butterflyman`, `dragonflyman`, and so on. + +```js +app.get(/.*fly$/, (req, res) => { + res.send('/.*fly$/'); +}); +``` + +## Route parameters + +Route parameters are named URL segments that are used to capture the values specified at their position in the URL. The captured values are populated in the `req.params` object, with the name of the route parameter specified in the path as their respective keys. + +``` +Route path: /users/:userId/books/:bookId +Request URL: http://localhost:3000/users/34/books/8989 +req.params: { "userId": "34", "bookId": "8989" } +``` + +To define routes with route parameters, simply specify the route parameters in the path of the route as shown below. + +```js +app.get('/users/:userId/books/:bookId', (req, res) => { + res.send(req.params); +}); +``` + + + +The name of route parameters must be made up of "word characters" ([A-Za-z0-9_]). + + + +Since the hyphen (`-`) and the dot (`.`) are interpreted literally, they can be used along with route parameters for useful purposes. + +``` +Route path: /flights/:from-:to +Request URL: http://localhost:3000/flights/LAX-SFO +req.params: { "from": "LAX", "to": "SFO" } +``` + +``` +Route path: /plantae/:genus.:species +Request URL: http://localhost:3000/plantae/Prunus.persica +req.params: { "genus": "Prunus", "species": "persica" } +``` + + + +In express 5, Regexp characters are not supported in route paths, for more information please +refer to the [migration guide](/en/guide/migrating-5#path-syntax). + + + +To have more control over the exact string that can be matched by a route parameter, you can append a regular expression in parentheses (`()`): + +``` +Route path: /user/:userId(\d+) +Request URL: http://localhost:3000/user/42 +req.params: {"userId": "42"} +``` + + + +Because the regular expression is usually part of a literal string, be sure to escape any `\` +characters with an additional backslash, for example `\d+`. + + + + +In Express 4.x, the `*` character in regular expressions is not interpreted in the usual way. As a workaround, use `{0,}` instead of `*`. This will likely be fixed in Express 5. + + +## Route handlers + +You can provide multiple callback functions that behave like [middleware](/en/guide/using-middleware) to handle a request. The only exception is that these callbacks might invoke `next('route')` to bypass the remaining route callbacks. You can use this mechanism to impose pre-conditions on a route, then pass control to subsequent routes if there's no reason to proceed with the current route. + +```js +app.get('/user/:id', (req, res, next) => { + if (req.params.id === '0') { + return next('route'); + } + res.send(`User ${req.params.id}`); +}); + +app.get('/user/:id', (req, res) => { + res.send('Special handler for user ID 0'); +}); +``` + +In this example: + +* `GET /user/5` → handled by first route → sends "User 5" +* `GET /user/0` → first route calls `next('route')`, skipping to the next matching `/user/:id` route + +Route handlers can be in the form of a function, an array of functions, or combinations of both, as shown in the following examples. + +A single callback function can handle a route. For example: + +```js +app.get('/example/a', (req, res) => { + res.send('Hello from A!'); +}); +``` + +More than one callback function can handle a route (make sure you specify the `next` object). For example: + +```js +app.get( + '/example/b', + (req, res, next) => { + console.log('the response will be sent by the next function ...'); + next(); + }, + (req, res) => { + res.send('Hello from B!'); + } +); +``` + +An array of callback functions can handle a route. For example: + +```js +const cb0 = function (req, res, next) { + console.log('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console.log('CB1'); + next(); +}; + +const cb2 = function (req, res) { + res.send('Hello from C!'); +}; + +app.get('/example/c', [cb0, cb1, cb2]); +``` + +A combination of independent functions and arrays of functions can handle a route. For example: + +```js +const cb0 = function (req, res, next) { + console.log('CB0'); + next(); +}; + +const cb1 = function (req, res, next) { + console.log('CB1'); + next(); +}; + +app.get( + '/example/d', + [cb0, cb1], + (req, res, next) => { + console.log('the response will be sent by the next function ...'); + next(); + }, + (req, res) => { + res.send('Hello from D!'); + } +); +``` + +## Response methods + +The methods on the response object (`res`) in the following table can send a response to the client, and terminate the request-response cycle. If none of these methods are called from a route handler, the client request will be left hanging. + +| Method | Description | +| --------------------------------------------- | ------------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | Prompt a file to be downloaded. | +| [res.end()](/en/5x/api#res.end) | End the response process. | +| [res.json()](/en/5x/api#res.json) | Send a JSON response. | +| [res.jsonp()](/en/5x/api#res.jsonp) | Send a JSON response with JSONP support. | +| [res.redirect()](/en/5x/api#res.redirect) | Redirect a request. | +| [res.render()](/en/5x/api#res.render) | Render a view template. | +| [res.send()](/en/5x/api#res.send) | Send a response of various types. | +| [res.sendFile()](/en/5x/api#res.sendFile) | Send a file as an octet stream. | +| [res.sendStatus()](/en/5x/api#res.sendStatus) | Set the response status code and send its string representation as the response body. | + +## app.route() + +You can create chainable route handlers for a route path by using `app.route()`. +Because the path is specified at a single location, creating modular routes is helpful, as is reducing redundancy and typos. For more information about routes, see: [Router() documentation](/en/5x/api#router). + +Here is an example of chained route handlers that are defined by using `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res.send('Get a random book'); + }) + .post((req, res) => { + res.send('Add a book'); + }) + .put((req, res) => { + res.send('Update the book'); + }); +``` + +## express.Router + +Use the `express.Router` class to create modular, mountable route handlers. A `Router` instance is a complete middleware and routing system; for this reason, it is often referred to as a "mini-app". + +The following example creates a router as a module, loads a middleware function in it, defines some routes, and mounts the router module on a path in the main app. + +Create a router file named `birds.js` in the app directory, with the following content: + +```js +const express = require('express'); +const router = express.Router(); + +// middleware that is specific to this router +const timeLog = (req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}; +router.use(timeLog); + +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Then, load the router module in the app: + +```js +const birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +The app will now be able to handle requests to `/birds` and `/birds/about`, as well as call the `timeLog` middleware function that is specific to the route. + +But if the parent route `/birds` has path parameters, it will not be accessible by default from the sub-routes. To make it accessible, you will need to pass the `mergeParams` option to the Router constructor [reference](/en/5x/api#app.use). + +```js +const router = express.Router({ mergeParams: true }); +``` diff --git a/src/content/docs/zh-tw/5x/guide/using-middleware.mdx b/src/content/docs/zh-tw/5x/guide/using-middleware.mdx new file mode 100644 index 0000000000..026542a234 --- /dev/null +++ b/src/content/docs/zh-tw/5x/guide/using-middleware.mdx @@ -0,0 +1,299 @@ +--- +title: Using middleware +description: Learn how to use middleware in Express.js applications, including application-level and router-level middleware, error handling, and integrating third-party middleware. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express is a routing and middleware web framework that has minimal functionality of its own: An Express application is essentially a series of middleware function calls. + +*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. + +Middleware functions can perform the following tasks: + +* Execute any code. +* Make changes to the request and the response objects. +* End the request-response cycle. +* Call the next middleware function in the stack. + +If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. + +An Express application can use the following types of middleware: + +* [Application-level middleware](#middleware.application) +* [Router-level middleware](#middleware.router) +* [Error-handling middleware](#middleware.error-handling) +* [Built-in middleware](#middleware.built-in) +* [Third-party middleware](#middleware.third-party) + +You can load application-level and router-level middleware with an optional mount path. +You can also load a series of middleware functions together, which creates a sub-stack of the middleware system at a mount point. + +## Application-level middleware + +Bind application-level middleware to an instance of the [app object](/en/5x/api#app) by using the `app.use()` and `app.METHOD()` functions, where `METHOD` is the HTTP method of the request that the middleware function handles (such as GET, PUT, or POST) in lowercase. + +This example shows a middleware function with no mount path. The function is executed every time the app receives a request. + +```js +const express = require('express'); +const app = express(); + +app.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); +``` + +This example shows a middleware function mounted on the `/user/:id` path. The function is executed for any type of +HTTP request on the `/user/:id` path. + +```js +app.use('/user/:id', (req, res, next) => { + console.log('Request Type:', req.method); + next(); +}); +``` + +This example shows a route and its handler function (middleware system). The function handles GET requests to the `/user/:id` path. + +```js +app.get('/user/:id', (req, res, next) => { + res.send('USER'); +}); +``` + +Here is an example of loading a series of middleware functions at a mount point, with a mount path. +It illustrates a middleware sub-stack that prints request info for any type of HTTP request to the `/user/:id` path. + +```js +app.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); +``` + +Route handlers enable you to define multiple routes for a path. The example below defines two routes for GET requests to the `/user/:id` path. The second route will not cause any problems, but it will never get called because the first route ends the request-response cycle. + +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. + +```js +app.get( + '/user/:id', + (req, res, next) => { + console.log('ID:', req.params.id); + next(); + }, + (req, res, next) => { + res.send('User Info'); + } +); + +// handler for the /user/:id path, which prints the user ID +app.get('/user/:id', (req, res, next) => { + res.send(req.params.id); +}); +``` + +To skip the rest of the middleware functions from a router middleware stack, call `next('route')` to pass control to the next route. + + + +`next('route')` will work only in middleware functions that were loaded by using the +`app.METHOD()` or `router.METHOD()` functions. + + + +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. + +```js +app.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next route + if (req.params.id === '0') next('route'); + // otherwise pass the control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // send a regular response + res.send('regular'); + } +); + +// handler for the /user/:id path, which sends a special response +app.get('/user/:id', (req, res, next) => { + res.send('special'); +}); +``` + +Middleware can also be declared in an array for reusability. + +This example shows an array with a middleware sub-stack that handles GET requests to the `/user/:id` path + +```js +function logOriginalUrl(req, res, next) { + console.log('Request URL:', req.originalUrl); + next(); +} + +function logMethod(req, res, next) { + console.log('Request Type:', req.method); + next(); +} + +const logStuff = [logOriginalUrl, logMethod]; +app.get('/user/:id', logStuff, (req, res, next) => { + res.send('User Info'); +}); +``` + +## Router-level middleware + +Router-level middleware works in the same way as application-level middleware, except it is bound to an instance of `express.Router()`. + +```js +const router = express.Router(); +``` + +Load router-level middleware by using the `router.use()` and `router.METHOD()` functions. + +The following example code replicates the middleware system that is shown above for application-level middleware, by using router-level middleware: + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// a middleware function with no mount path. This code is executed for every request to the router +router.use((req, res, next) => { + console.log('Time:', Date.now()); + next(); +}); + +// a middleware sub-stack shows request info for any type of HTTP request to the /user/:id path +router.use( + '/user/:id', + (req, res, next) => { + console.log('Request URL:', req.originalUrl); + next(); + }, + (req, res, next) => { + console.log('Request Type:', req.method); + next(); + } +); + +// a middleware sub-stack that handles GET requests to the /user/:id path +router.get( + '/user/:id', + (req, res, next) => { + // if the user ID is 0, skip to the next router + if (req.params.id === '0') next('route'); + // otherwise pass control to the next middleware function in this stack + else next(); + }, + (req, res, next) => { + // render a regular page + res.render('regular'); + } +); + +// handler for the /user/:id path, which renders a special page +router.get('/user/:id', (req, res, next) => { + console.log(req.params.id); + res.render('special'); +}); + +// mount the router on the app +app.use('/', router); +``` + +To skip the rest of the router's middleware functions, call `next('router')` +to pass control back out of the router instance. + +This example shows a middleware sub-stack that handles GET requests to the `/user/:id` path. + +```js +const express = require('express'); +const app = express(); +const router = express.Router(); + +// predicate the router with a check and bail out when needed +router.use((req, res, next) => { + if (!req.headers['x-auth']) return next('router'); + next(); +}); + +router.get('/user/:id', (req, res) => { + res.send('hello, user!'); +}); + +// use the router and 401 anything falling through +app.use('/admin', router, (req, res) => { + res.sendStatus(401); +}); +``` + +## Error-handling middleware + + + +Error-handling middleware always takes *four* arguments. You must provide four arguments to +identify it as an error-handling middleware function. Even if you don't need to use the `next` +object, you must specify it to maintain the signature. Otherwise, the `next` object will be +interpreted as regular middleware and will fail to handle errors. + + + +Define error-handling middleware functions in the same way as other middleware functions, except with four arguments instead of three, specifically with the signature `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +For details about error-handling middleware, see: [Error handling](/en/guide/error-handling). + +## Built-in middleware + +Starting with version 4.x, Express no longer depends on [Connect](https://github.com/senchalabs/connect). The middleware +functions that were previously included with Express are now in separate modules; see [the list of middleware functions](https://github.com/senchalabs/connect#middleware). + +Express has the following built-in middleware functions: + +* [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. +* [express.json](/en/5x/api#express.json) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** +* [express.urlencoded](/en/5x/api#express.urlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** + +## Third-party middleware + +Use third-party middleware to add functionality to Express apps. + +Install the Node.js module for the required functionality, then load it in your app at the application level or at the router level. + +The following example illustrates installing and loading the cookie-parsing middleware function `cookie-parser`. + +```bash +$ npm install cookie-parser +``` + +```js +const express = require('express'); +const app = express(); +const cookieParser = require('cookie-parser'); + +// load the cookie-parsing middleware +app.use(cookieParser()); +``` + +For a partial list of third-party middleware functions that are commonly used with Express, see: [Third-party middleware](../resources/middleware). diff --git a/src/content/docs/zh-tw/5x/guide/using-template-engines.mdx b/src/content/docs/zh-tw/5x/guide/using-template-engines.mdx new file mode 100644 index 0000000000..7095bc6dd5 --- /dev/null +++ b/src/content/docs/zh-tw/5x/guide/using-template-engines.mdx @@ -0,0 +1,63 @@ +--- +title: Using template engines with Express +description: Discover how to integrate and use template engines like Pug, Handlebars, and EJS with Express.js to render dynamic HTML pages efficiently. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +A *template engine* enables you to use static template files in your application. At runtime, the template engine replaces +variables in a template file with actual values, and transforms the template into an HTML file sent to the client. +This approach makes it easier to design an HTML page. + +The [Express application generator](/en/starter/generator) uses [Pug](https://pugjs.org/api/getting-started.html) as its default, but it also supports [Handlebars](https://www.npmjs.com/package/handlebars), and [EJS](https://www.npmjs.com/package/ejs), among others. + +To render template files, set the following [application setting properties](/en/4x/api#app.set), in the default `app.js` created by the generator: + +* `views`, the directory where the template files are located. Eg: `app.set('views', './views')`. + This defaults to the `views` directory in the application root directory. +* `view engine`, the template engine to use. For example, to use the Pug template engine: `app.set('view engine', 'pug')`. + +Then install the corresponding template engine npm package; for example to install Pug: + +```bash +$ npm install pug --save +``` + + +Express-compliant template engines such as Pug export a function named `__express(filePath, options, callback)`, +which `res.render()` calls to render the template code. + +Some template engines do not follow this convention. The [@ladjs/consolidate](https://www.npmjs.com/package/@ladjs/consolidate) +library follows this convention by mapping all of the popular Node.js template engines, and therefore works seamlessly within Express. + + + +After the view engine is set, you don't have to specify the engine or load the template engine module in your app; +Express loads the module internally, for example: + +```js +app.set('view engine', 'pug'); +``` + +Then, create a Pug template file named `index.pug` in the `views` directory, with the following content: + +```pug +html + head + title= title + body + h1= message +``` + +Create a route to render the `index.pug` file. If the `view engine` property is not set, +you must specify the extension of the `view` file. Otherwise, you can omit it. + +```js +app.get('/', (req, res) => { + res.render('index', { title: 'Hey', message: 'Hello there!' }); +}); +``` + +When you make a request to the home page, the `index.pug` file will be rendered as HTML. + +The view engine cache does not cache the contents of the template's output, only the underlying template itself. The view is still re-rendered with every request even when the cache is on. diff --git a/src/content/docs/zh-tw/5x/guide/writing-middleware.mdx b/src/content/docs/zh-tw/5x/guide/writing-middleware.mdx new file mode 100644 index 0000000000..a22cd12f84 --- /dev/null +++ b/src/content/docs/zh-tw/5x/guide/writing-middleware.mdx @@ -0,0 +1,209 @@ +--- +title: Writing middleware for use in Express apps +description: Learn how to write custom middleware functions for Express.js applications, including examples and best practices for enhancing request and response handling. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. + +Middleware functions can perform the following tasks: + +* Execute any code. +* Make changes to the request and the response objects. +* End the request-response cycle. +* Call the next middleware in the stack. + +If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. + +The following figure shows the elements of a middleware function call: + +![Elements of a middleware function call](/images/express-mw.png) + +Starting with Express 5, middleware functions that return a Promise will call `next(value)` when they reject or throw an error. `next` will be called with either the rejected value or the thrown Error. + +## Example + +Here is an example of a simple "Hello World" Express application. +The remainder of this article will define and add three middleware functions to the application: +one called `myLogger` that prints a simple log message, one called `requestTime` that +displays the timestamp of the HTTP request, and one called `validateCookies` that validates incoming cookies. + +```js +const express = require('express'); +const app = express(); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +### Middleware function myLogger + +Here is a simple example of a middleware function called "myLogger". This function just prints +"LOGGED" when a request to the app passes through it. The middleware function is assigned to a +variable named `myLogger`. + +```js +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; +``` + + + +Notice the call above to `next()`. Calling this function invokes the next middleware function in +the app. The `next()` function is not a part of the Node.js or Express API, but is the third +argument that is passed to the middleware function. The `next()` function could be named anything, +but by convention it is always named "next". To avoid confusion, always use this convention. + + + +To load the middleware function, call `app.use()`, specifying the middleware function. +For example, the following code loads the `myLogger` middleware function before the route to the root path (/). + +```js +const express = require('express'); +const app = express(); + +const myLogger = function (req, res, next) { + console.log('LOGGED'); + next(); +}; + +app.use(myLogger); + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(3000); +``` + +Every time the app receives a request, it prints the message "LOGGED" to the terminal. + +The order of middleware loading is important: middleware functions that are loaded first are also executed first. + +If `myLogger` is loaded after the route to the root path, the request never reaches it and the app doesn't print "LOGGED", because the route handler of the root path terminates the request-response cycle. + +The middleware function `myLogger` simply prints a message, then passes on the request to the next middleware function in the stack by calling the `next()` function. + +### Middleware function requestTime + +Next, we'll create a middleware function called "requestTime" and add a property called `requestTime` +to the request object. + +```js +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; +``` + +The app now uses the `requestTime` middleware function. Also, the callback function of the root path route uses the property that the middleware function adds to `req` (the request object). + +```js +const express = require('express'); +const app = express(); + +const requestTime = function (req, res, next) { + req.requestTime = Date.now(); + next(); +}; + +app.use(requestTime); + +app.get('/', (req, res) => { + let responseText = 'Hello World!
'; + responseText += `Requested at: ${req.requestTime}`; + res.send(responseText); +}); + +app.listen(3000); +``` + +When you make a request to the root of the app, the app now displays the timestamp of your request in the browser. + +### Middleware function validateCookies + +Finally, we'll create a middleware function that validates incoming cookies and sends a 400 response if cookies are invalid. + +Here's an example function that validates cookies with an external async service. + +```js +async function cookieValidator(cookies) { + try { + await externallyValidateCookie(cookies.testCookie); + } catch { + throw new Error('Invalid cookies'); + } +} +``` + +Here, we use the [`cookie-parser`](/en/resources/middleware/cookie-parser) middleware to parse incoming cookies off the `req` object and pass them to our `cookieValidator` function. The `validateCookies` middleware returns a Promise that upon rejection will automatically trigger our error handler. + +```js +const express = require('express'); +const cookieParser = require('cookie-parser'); +const cookieValidator = require('./cookieValidator'); + +const app = express(); + +async function validateCookies(req, res, next) { + await cookieValidator(req.cookies); + next(); +} + +app.use(cookieParser()); + +app.use(validateCookies); + +// error handler +app.use((err, req, res, next) => { + res.status(400).send(err.message); +}); + +app.listen(3000); +``` + + + +Note how `next()` is called after `await cookieValidator(req.cookies)`. This ensures that if +`cookieValidator` resolves, the next middleware in the stack will get called. If you pass anything +to the `next()` function (except the string `'route'` or `'router'`), Express regards the current +request as being an error and will skip any remaining non-error handling routing and middleware +functions. + + + +Because you have access to the request object, the response object, the next middleware function in the stack, and the whole Node.js API, the possibilities with middleware functions are endless. + +For more information about Express middleware, see: [Using Express middleware](/en/guide/using-middleware). + +## Configurable middleware + +If you need your middleware to be configurable, export a function which accepts an options object or other parameters, which, then returns the middleware implementation based on the input parameters. + +File: `my-middleware.js` + +```js +module.exports = function (options) { + return function (req, res, next) { + // Implement the middleware function based on the options object + next(); + }; +}; +``` + +The middleware can now be used as shown below. + +```js +const mw = require('./my-middleware.js'); + +app.use(mw({ option1: '1', option2: '2' })); +``` + +Refer to [cookie-session](https://github.com/expressjs/cookie-session) and [compression](https://github.com/expressjs/compression) for examples of configurable middleware. diff --git a/src/content/docs/zh-tw/5x/starter/basic-routing.mdx b/src/content/docs/zh-tw/5x/starter/basic-routing.mdx new file mode 100644 index 0000000000..35d674808b --- /dev/null +++ b/src/content/docs/zh-tw/5x/starter/basic-routing.mdx @@ -0,0 +1,67 @@ +--- +title: Basic routing +description: Learn the fundamentals of routing in Express.js applications, including how to define routes, handle HTTP methods, and create route handlers for your web server. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*Routing* refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). + +Each route can have one or more handler functions, which are executed when the route is matched. + +Route definition takes the following structure: + +```js +app.METHOD(PATH, HANDLER); +``` + +Where: + +* `app` is an instance of `express`. +* `METHOD` is an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in lowercase. +* `PATH` is a path on the server. +* `HANDLER` is the function executed when the route is matched. + + + +This tutorial assumes that an instance of `express` named `app` is created and the server is +running. If you are not familiar with creating an app and starting it, see the Hello world +example. + + + +The following examples illustrate defining simple routes. + +Respond with `Hello World!` on the homepage: + +```js +app.get('/', (req, res) => { + res.send('Hello World!'); +}); +``` + +Respond to a POST request on the root route (`/`), the application's home page: + +```js +app.post('/', (req, res) => { + res.send('Got a POST request'); +}); +``` + +Respond to a PUT request to the `/user` route: + +```js +app.put('/user', (req, res) => { + res.send('Got a PUT request at /user'); +}); +``` + +Respond to a DELETE request to the `/user` route: + +```js +app.delete('/user', (req, res) => { + res.send('Got a DELETE request at /user'); +}); +``` + +For more details about routing, see the [routing guide](/en/guide/routing). diff --git a/src/content/docs/zh-tw/5x/starter/examples.mdx b/src/content/docs/zh-tw/5x/starter/examples.mdx new file mode 100644 index 0000000000..eccdf984c2 --- /dev/null +++ b/src/content/docs/zh-tw/5x/starter/examples.mdx @@ -0,0 +1,49 @@ +--- +title: Express examples +description: Explore a collection of Express.js application examples covering various use cases, integrations, and advanced configurations to help you learn and build your projects. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +This page contains list of examples using Express. + +* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Authentication with login and password +* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - HTTP content negotiation +* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Working with cookie-based sessions +* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Working with cookies +* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transferring files to client +* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Working with Embedded JavaScript templating (ejs) +* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Creating error pages +* [error](https://github.com/expressjs/express/tree/master/examples/error) - Working with error middleware +* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Simple request handler +* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown as template engine +* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Working with multiple Express routers +* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - MVC-style controllers +* [online](https://github.com/expressjs/express/tree/master/examples/online) - Tracking online user activity with `online` and `redis` packages +* [params](https://github.com/expressjs/express/tree/master/examples/params) - Working with route parameters +* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Multiple HTTP operations on the same resource +* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organizing routes using a map +* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Working with route middleware +* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizing routes per each resource +* [search](https://github.com/expressjs/express/tree/master/examples/search) - Search API +* [session](https://github.com/expressjs/express/tree/master/examples/session) - User sessions +* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Serving static files +* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Working with virtual hosts +* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Rendering views dynamically +* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Saving data in request object between middleware calls +* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Simple API service + +## Additional examples + +These are some additional examples with more extensive integrations. + + + +This information refers to third-party sites, products, or modules that are not maintained by the +Expressjs team. Listing here does not constitute an endorsement or recommendation from the +Expressjs project team. + + + +* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app with Express and Next.js using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM diff --git a/src/content/docs/zh-tw/5x/starter/faq.md b/src/content/docs/zh-tw/5x/starter/faq.md new file mode 100644 index 0000000000..1adcb7be0e --- /dev/null +++ b/src/content/docs/zh-tw/5x/starter/faq.md @@ -0,0 +1,90 @@ +--- +title: FAQ +description: Find answers to frequently asked questions about Express.js, including topics on application structure, models, authentication, template engines, error handling, and more. +--- + +## How should I structure my application? + +There is no definitive answer to this question. The answer depends +on the scale of your application and the team that is involved. To be as +flexible as possible, Express makes no assumptions in terms of structure. + +Routes and other application-specific logic can live in as many files +as you wish, in any directory structure you prefer. View the following +examples for inspiration: + +- [Route listings](https://github.com/expressjs/express/blob/4.13.1/examples/route-separation/index.js#L32-L47) +- [Route map](https://github.com/expressjs/express/blob/4.13.1/examples/route-map/index.js#L52-L66) +- [MVC style controllers](https://github.com/expressjs/express/tree/master/examples/mvc) + +Also, there are third-party extensions for Express, which simplify some of these patterns: + +- [Resourceful routing](https://github.com/expressjs/express-resource) + +## How do I define models? + +Express has no notion of a database. This concept is +left up to third-party Node modules, allowing you to +interface with nearly any database. + +See [LoopBack](http://loopback.io) for an Express-based framework that is centered around models. + +## How can I authenticate users? + +Authentication is another opinionated area that Express does not +venture into. You may use any authentication scheme you wish. +For a simple username / password scheme, see [this example](https://github.com/expressjs/express/tree/master/examples/auth). + +## Which template engines does Express support? + +Express supports any template engine that conforms with the `(path, locals, callback)` signature. +To normalize template engine interfaces and caching, see the +[consolidate.js](https://github.com/visionmedia/consolidate.js) +project for support. Unlisted template engines might still support the Express signature. + +For more information, see [Using template engines with Express](/en/guide/using-template-engines). + +## How do I handle 404 responses? + +In Express, 404 responses are not the result of an error, so +the error-handler middleware will not capture them. This behavior is +because a 404 response simply indicates the absence of additional work to do; +in other words, Express has executed all middleware functions and routes, +and found that none of them responded. All you need to +do is add a middleware function at the very bottom of the stack (below all other functions) +to handle a 404 response: + +```js +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); +``` + +Add routes dynamically at runtime on an instance of `express.Router()` +so the routes are not superseded by a middleware function. + +## How do I setup an error handler? + +You define error-handling middleware in the same way as other middleware, +except with four arguments instead of three; specifically with the signature `(err, req, res, next)`: + +```js +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +For more information, see [Error handling](/en/guide/error-handling). + +## How do I render plain HTML? + +You don't! There's no need to "render" HTML with the `res.render()` function. +If you have a specific file, use the `res.sendFile()` function. +If you are serving many assets from a directory, use the `express.static()` +middleware function. + +## What version of Node.js does Express require? + +- [Express 4.x](/en/4x/api) requires Node.js 0.10 or higher. +- [Express 5.x](/en/5x/api) requires Node.js 18 or higher. diff --git a/src/content/docs/zh-tw/5x/starter/generator.mdx b/src/content/docs/zh-tw/5x/starter/generator.mdx new file mode 100644 index 0000000000..859bec927e --- /dev/null +++ b/src/content/docs/zh-tw/5x/starter/generator.mdx @@ -0,0 +1,125 @@ +--- +title: Express application generator +description: Learn how to use the Express application generator tool to quickly create a skeleton for your Express.js applications, streamlining setup and configuration. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Use the application generator tool, `express-generator`, to quickly create an application skeleton. + +You can run the application generator with the `npx` command (available in Node.js 8.2.0). + +```bash +$ npx express-generator +``` + +For earlier Node versions, install the application generator as a global npm package and then launch it: + +```bash +$ npm install -g express-generator +$ express +``` + +Display the command options with the `-h` option: + +```bash +$ express -h + + Usage: express [options] [dir] + + Options: + + -h, --help output usage information + --version output the version number + -e, --ejs add ejs engine support + --hbs add handlebars engine support + --pug add pug engine support + -H, --hogan add hogan.js engine support + --no-view generate without view engine + -v, --view add view support (ejs|hbs|hjs|jade|pug|twig|vash) (defaults to jade) + -c, --css add stylesheet support (less|stylus|compass|sass) (defaults to plain css) + --git add .gitignore + -f, --force force on non-empty directory +``` + +For example, the following creates an Express app named *myapp*. The app will be created in a folder named *myapp* in the current working directory and the view engine will be set to Pug: + +```bash +$ express --view=pug myapp + + create : myapp + create : myapp/package.json + create : myapp/app.js + create : myapp/public + create : myapp/public/javascripts + create : myapp/public/images + create : myapp/routes + create : myapp/routes/index.js + create : myapp/routes/users.js + create : myapp/public/stylesheets + create : myapp/public/stylesheets/style.css + create : myapp/views + create : myapp/views/index.pug + create : myapp/views/layout.pug + create : myapp/views/error.pug + create : myapp/bin + create : myapp/bin/www +``` + +Then install dependencies: + +```bash +$ cd myapp +$ npm install +``` + +On MacOS or Linux, run the app with this command: + +```bash +$ DEBUG=myapp:* npm start +``` + +On Windows Command Prompt, use this command: + +```bash +> set DEBUG=myapp:* & npm start +``` + +On Windows PowerShell, use this command: + +```bash +PS> $env:DEBUG='myapp:*'; npm start +``` + +Then, load `http://localhost:3000/` in your browser to access the app. + +The generated app has the following directory structure: + +```bash +. +├── app.js +├── bin +│ └── www +├── package.json +├── public +│ ├── images +│ ├── javascripts +│ └── stylesheets +│ └── style.css +├── routes +│ ├── index.js +│ └── users.js +└── views + ├── error.pug + ├── index.pug + └── layout.pug + +7 directories, 9 files +``` + + + +The app structure created by the generator is just one of many ways to structure Express apps. +Feel free to use this structure or modify it to best suit your needs. + + diff --git a/src/content/docs/zh-tw/5x/starter/hello-world.mdx b/src/content/docs/zh-tw/5x/starter/hello-world.mdx new file mode 100644 index 0000000000..d92beecd0a --- /dev/null +++ b/src/content/docs/zh-tw/5x/starter/hello-world.mdx @@ -0,0 +1,54 @@ +--- +title: Hello world example +description: Get started with Express.js by building a simple 'Hello World' application, demonstrating the basic setup and server creation for beginners. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Embedded below is essentially the simplest Express app you can create. It is a single file app +— *not* what you'd get if you use the [Express generator](/en/starter/generator), which +creates the scaffolding for a full app with numerous JavaScript files, Jade templates, and +sub-directories for various purposes. + + + +```js +const express = require('express'); +const app = express(); +const port = 3000; + +app.get('/', (req, res) => { + res.send('Hello World!'); +}); + +app.listen(port, () => { + console.log(`Example app listening on port ${port}`); +}); +``` + +This app starts a server and listens on port 3000 for connections. The app responds with "Hello World!" for requests +to the root URL (`/`) or *route*. For every other path, it will respond with a **404 Not Found**. + +## Running Locally + +First create a directory named `myapp`, change to it and run `npm init`. Then, install `express` as a dependency, as per the [installation guide](/en/starter/installing). + +In the `myapp` directory, create a file named `app.js` and copy the code from the example above. + + + +The `req` (request) and `res` (response) are the exact same objects that Node provides, so you can +invoke `req.pipe()`, `req.on('data', callback)`, and anything else you would do without Express +involved. + + + +Run the app with the following command: + +```bash +$ node app.js +``` + +Then, load `http://localhost:3000/` in a browser to see the output. diff --git a/src/content/docs/zh-tw/5x/starter/installing.mdx b/src/content/docs/zh-tw/5x/starter/installing.mdx new file mode 100644 index 0000000000..f6dc8220d4 --- /dev/null +++ b/src/content/docs/zh-tw/5x/starter/installing.mdx @@ -0,0 +1,41 @@ +--- +title: Installing +description: Learn how to install Express.js in your Node.js environment, including setting up your project directory and managing dependencies with npm. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Before you begin, make sure you have [Node.js](https://nodejs.org/) 18 or higher installed. Then, create a directory for your application and navigate into it. + +```bash +mkdir myapp +cd myapp +``` + +Use the `npm init` command to create a `package.json` file for your application. +For more information on how `package.json` works, see [Specifics of npm's package.json handling](https://docs.npmjs.com/files/package.json). + +```bash +npm init +``` + +This command prompts you for a number of things, such as the name and version of your application. +For now, you can simply hit RETURN to accept the defaults for most of them, with the following exception: + +``` +entry point: (index.js) +``` + +Enter `app.js`, or whatever you want the name of the main file to be. If you want it to be `index.js`, hit RETURN to accept the suggested default file name. + +Now, install Express in the `myapp` directory and save it in the dependencies list. For example: + +```bash +npm install express +``` + +To install Express temporarily and not add it to the dependencies list: + +```bash +npm install express --no-save +``` diff --git a/src/content/docs/zh-tw/5x/starter/static-files.mdx b/src/content/docs/zh-tw/5x/starter/static-files.mdx new file mode 100644 index 0000000000..98855e0d05 --- /dev/null +++ b/src/content/docs/zh-tw/5x/starter/static-files.mdx @@ -0,0 +1,82 @@ +--- +title: Serving static files in Express +description: Understand how to serve static files like images, CSS, and JavaScript in Express.js applications using the built-in 'static' middleware. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +To serve static files such as images, CSS files, and JavaScript files, use the `express.static` built-in middleware function in Express. + +The function signature is: + +```js +express.static(root, [options]); +``` + +The `root` argument specifies the root directory from which to serve static assets. +For more information on the `options` argument, see [express.static](/en/5x/api#express.static). + +For example, use the following code to serve images, CSS files, and JavaScript files in a directory named `public`: + +```js +app.use(express.static('public')); +``` + +Now, you can load the files that are in the `public` directory: + +```text +http://localhost:3000/images/kitten.jpg +http://localhost:3000/css/style.css +http://localhost:3000/js/app.js +http://localhost:3000/images/bg.png +http://localhost:3000/hello.html +``` + + + +Express looks up the files relative to the static directory, so the name of the static directory +is not part of the URL. + + + +To use multiple static assets directories, call the `express.static` middleware function multiple times: + +```js +app.use(express.static('public')); +app.use(express.static('files')); +``` + +Express looks up the files in the order in which you set the static directories with the `express.static` middleware function. + + + +For best results, use a reverse +proxy cache to improve performance of +serving static assets. + + + +To create a virtual path prefix (where the path does not actually exist in the file system) for files that are served by the `express.static` function, [specify a mount path](/en/5x/api#app.use) for the static directory, as shown below: + +```js +app.use('/static', express.static('public')); +``` + +Now, you can load the files that are in the `public` directory from the `/static` path prefix. + +```text +http://localhost:3000/static/images/kitten.jpg +http://localhost:3000/static/css/style.css +http://localhost:3000/static/js/app.js +http://localhost:3000/static/images/bg.png +http://localhost:3000/static/hello.html +``` + +However, the path that you provide to the `express.static` function is relative to the directory from where you launch your `node` process. If you run the express app from another directory, it's safer to use the absolute path of the directory that you want to serve: + +```js +const path = require('path'); +app.use('/static', express.static(path.join(__dirname, 'public'))); +``` + +For more details about the `serve-static` function and its options, see [serve-static](/en/resources/middleware/serve-static). diff --git a/src/content/pages/de/advanced/best-practice-performance.md b/src/content/pages/de/advanced/best-practice-performance.md new file mode 100644 index 0000000000..615d160130 --- /dev/null +++ b/src/content/pages/de/advanced/best-practice-performance.md @@ -0,0 +1,305 @@ +--- +title: 'Best Practices: Leistung und Zuverlässigkeit' +description: Entdecken Sie Performance und Zuverlässigkeits-Best Practices für Express-Apps in der Produktion, die Code-Optimierungen und Umgebungs-Setups für optimale Performance abdecken. +--- + +Dieser Artikel befasst sich mit der Leistungsfähigkeit und der Zuverlässigkeit der besten Verfahren für Express-Anwendungen, die in der Produktion eingesetzt werden. + +Dieses Thema fällt eindeutig in die "Devops"-Welt, die sowohl traditionelle Entwicklung als auch Operationen umfasst. Dementsprechend sind die Informationen in zwei Teile aufgeteilt: + +- Dinge in Ihrem Code zu tun (dev part): + - [Benutze gzip Kompression](#use-gzip-compression) + - [Keine synchronen Funktionen](#dont-use-synchronous-functions) + - [Logging korrekt](#do-logging-correctly) + - [Ausnahmen richtig behandeln](#handle-exceptions-properly) +- Dinge zu tun in Ihrer Umgebung / in Ihrer Umgebung (der Ops-Teil): + - [Setze NODE_ENV auf "Produktion"](#set-node_env-to-production) + - [Stelle sicher, dass deine App automatisch neu startet](#ensure-your-app-automatically-restarts) + - [Starte deine App in einem Cluster](#run-your-app-in-a-cluster) + - [Cache-Anfrageergebnisse](#cache-request-results) + - [Lastausgleich verwenden](#use-a-load-balancer) + - [Reverse Proxy](#use-a-reverse-proxy) verwenden + +## Dinge in deinem Code zu tun + +Hier sind einige Dinge, die Sie in Ihrem Code tun können, um die Leistung Ihrer Anwendung zu verbessern: + +- [Benutze gzip Kompression](#use-gzip-compression) +- [Keine synchronen Funktionen](#dont-use-synchronous-functions) +- [Logging korrekt](#do-logging-correctly) +- [Ausnahmen richtig behandeln](#handle-exceptions-properly) + +### Gzip Komprimierung verwenden + +Gzip-Komprimierung kann die Reaktionskörper erheblich verringern und damit die Geschwindigkeit einer Web-App erhöhen. Benutzen Sie die [compression](https://www.npmjs.com/package/compression) Middleware für gzip Komprimierung in Ihrer Express-App. Zum Beispiel: + +```js +const compression = require('compression'); +const express = require('express'); +const app = express(); + +app.use(compression()); +``` + +Für eine stark frequentierte Website in der Produktion, der beste Weg zur Komprimierung ist die Implementierung auf umgekehrter Proxyebene (siehe [Reverse Proxy](#use-a-reverse-proxy)) . In diesem Fall brauchen Sie keine Komprimierungsmittelware. Details zum Aktivieren der gzip-Komprimierung in Nginx finden Sie unter [Module ngx_http_gzip_module](http://nginx.org/en/docs/http/ngx_http_gzip_module) in der Nginx-Dokumentation. + +### Keine synchronen Funktionen verwenden + +Synchronische Funktionen und Methoden binden den Ausführungsprozess bis sie zurückkehren. Ein einzelner Aufruf einer synchronen Funktion kann in ein paar Mikrosekunden oder Millisekunden zurückgegeben werden auf Websites mit hohem Traffic jedoch tragen diese Anrufe dazu bei, die Performance der App zu reduzieren. Vermeiden Sie ihren Einsatz in der Produktion. + +Obwohl Node und viele Module synchrone und asynchrone Versionen ihrer Funktionen liefern, verwenden Sie immer die asynchrone Version in der Produktion. Die einzige Zeit, in der eine synchrone Funktion gerechtfertigt werden kann, ist beim ersten Start. + +Du kannst das `--trace-sync-io` Kommandozeilen-Flag verwenden, um eine Warnung und einen Stack-Trace zu drucken, wann immer deine Anwendung eine synchrone API verwendet. Natürlich möchten Sie dies nicht in der Produktion verwenden, sondern vielmehr sicherstellen, dass Ihr Code produktionsbereit ist. Weitere Informationen finden Sie in der [Knoten Kommandozeilenoptionen Dokumentation](https://nodejs.org/api/cli#cli_trace_sync_io) . + +### Logging korrekt + +Im Allgemeinen gibt es zwei Gründe für die Protokollierung aus Ihrer App: Für das Debuggen und für die Protokollierung von App-Aktivitäten (im Wesentlichen alles andere). Die Verwendung von `console.log()` oder `console.error()` zum Drucken von Logmeldungen an das Terminal ist gängige Praxis in der Entwicklung. Aber [diese Funktionen sind synchronisiert](https://nodejs.org/api/console#console), wenn das Ziel ein Terminal oder eine Datei ist so dass sie nicht für die Produktion geeignet sind, es sei denn, Sie rollen die Ausgabe zu einem anderen Programm. + +#### Zum Debuggen + +Wenn du zum Debuggen loggst, benutze anstelle von `console.log()` ein spezielles Debugging-Modul wie [debug](https://www.npmjs.com/package/debug). Dieses Modul ermöglicht es Ihnen, die DEBUG Umgebungsvariable zu verwenden, um zu kontrollieren, welche Debug-Meldungen an `console.error()` gesendet werden, falls vorhanden. Um deine App rein asynchron zu halten, solltest du trotzdem `console.error()` zu einem anderen Programm weiterleiten. Aber dann bist du nicht wirklich in der Produktion zu debuggen, oder? + +#### Für App-Aktivitäten + +Wenn Sie App-Aktivitäten protokollieren (zum Beispiel Traffic oder API-Aufrufe), anstatt „Konsole“. og()\`, verwende eine Logging-Bibliothek wie [Pino](https://www.npmjs.com/package/pino), die schnellste und effizienteste verfügbare Option. + +### Ausnahmen richtig handhaben + +Knoten-Apps stürzen ab, wenn sie auf eine nicht gefangene Ausnahme stoßen. Wenn Sie Ausnahmen nicht bearbeiten und entsprechende Maßnahmen ergreifen, wird Ihre Express-App zum Absturz bringen und offline gehen. Wenn du dem Rat folgst [Stelle sicher, dass deine App automatisch neu startet](#ensure-your-app-automatically-restarts) unten, dann wird deine App von einem Absturz erholt. Glücklicherweise haben Express-Apps in der Regel eine kurze Startzeit. Nichtsdestotrotz wollen Sie einen Absturz vermeiden, und dazu müssen Sie die Ausnahmen ordentlich behandeln. + +Um sicherzustellen, dass Sie mit allen Ausnahmen umgehen, verwenden Sie folgende Techniken: + +- [Versuchscatch](#use-try-catch) +- [Versprechungen verwenden](#use-promises) + +Bevor Sie in diese Themen eintauchen, sollten Sie ein grundlegendes Verständnis von Node/Express-Fehlerbehandlung haben: Verwendung von Fehler-First Callbacks und Verbreitung von Fehlern in Middleware. Knoten verwendet eine "error-first callback"-Konvention um Fehler aus asynchronen Funktionen zurückzugeben, wobei der erste Parameter der Callback-Funktion das Fehlerobjekt ist, gefolgt von Ergebnisdaten in folgenden Parametern. Um keinen Fehler anzugeben, übergeben Sie Null als ersten Parameter. Die Callback-Funktion muss entsprechend der ersten Callback-Konvention folgen, um den Fehler sinnvoll zu bearbeiten. Und in Express ist es am besten, die next() Funktion zu nutzen, um Fehler über die Middleware-Kette zu verbreiten. + +Für mehr über die Grundlagen der Fehlerbehandlung, siehe: + +- [Fehler beim Umgang mit Node.js](https://www.tritondatacenter.com/node-js/production/design/errors) + +#### Versuchsfang verwenden + +Try-catch ist eine JavaScript-Sprachkonstruktion, die Sie verwenden können, um Ausnahmen im synchronen Code zu fangen. Verwenden Sie zum Beispiel den versuchen Catch, um JSON-Parsing-Fehler wie unten gezeigt zu behandeln. + +Hier ist ein Beispiel für die Verwendung von "try-catch", um eine mögliche Prozessabsturzausnahme zu bewältigen. +Diese Middleware-Funktion akzeptiert einen Abfragefeldparameter namens "params", das ein JSON-Objekt ist. + +```js +app.get('/search', (req, res) => { + // Simulating async operation + setImmediate(() => { + const jsonStr = req.query.params; + try { + const jsonObj = JSON.parse(jsonStr); + res.send('Success'); + } catch (e) { + res.status(400).send('Invalid JSON string'); + } + }); +}); +``` + +Der Versuch funktioniert jedoch nur für synchrone Code. Da die Knotenplattform primär asynchron ist (insbesondere in einer Produktionsumgebung), wird der Versuch nicht viele Ausnahmen fangen. + +#### Versprechen verwenden + +Wenn ein Fehler in einer `async` Funktion ausgelöst wird oder ein abgelehntes Versprechen in einer `async` Funktion erwartet wird, diese Fehler werden an den Fehlerhandler übergeben, als ob `next(err)` aufgerufen würde + +```js +app.get('/', async (req, res, next) => { + const data = await userData(); // If this promise fails, it will automatically call `next(err)` to handle the error. + + res.send(data); +}); + +app.use((err, req, res, next) => { + res.status(err.status ?? 500).send({ error: err.message }); +}); +``` + +Außerdem können Sie asynchrone Funktionen für Ihre Middleware verwenden und der Router verarbeitet Fehler, wenn das Versprechen fehlschlägt, zum Beispiel: + +```js +app.use(async (req, res, next) => { + req.locals.user = await getUser(req); + + next(); // This will be called if the promise does not throw an error. +}); +``` + +Best Practices ist es, Fehler so nah wie möglich an der Website zu behandeln. So während dies jetzt im Router behandelt wird, ist es am besten, den Fehler in der Middleware zu fangen und ihn zu bearbeiten, ohne sich auf eine separate Middleware zu verlassen. + +#### Was nicht zu tun + +Eine Sache, die du _nicht_ tun solltest ist, auf das `uncaptException` Event zu hören emittiert, wenn eine Ausnahme den ganzen Weg zurück zur Ereignis-Schleife weht. Das Hinzufügen eines Ereignis-Listeners für `uncaughtException` ändert das Standardverhalten des Prozesses, der auf eine Ausnahme stößt; wird der Prozess trotz der Ausnahme weiterhin laufen. Dies könnte nach einer guten Möglichkeit klingen, um zu verhindern, dass Ihre App abstürzt, aber die Anwendung nach einer nicht gefangenen Ausnahme weiterhin zu laufen ist eine gefährliche Praxis und wird nicht empfohlen, weil der Zustand des Prozesses unzuverlässig und unberechenbar wird. + +Zusätzlich wird die Verwendung von `uncaughtException` offiziell als [crude]anerkannt (https://nodejs.org/api/process#process_event_uncaughtexception). Also ist das Hören auf `uncaughtException` eine schlechte Idee. Aus diesem Grund empfehlen wir Dinge wie mehrere Prozesse und Supervisoren: Absturz und Neustart sind oft der zuverlässigste Weg, um einen Fehler zu beheben. + +Wir empfehlen auch nicht [domains]zu verwenden (https://nodejs.org/api/domain). Es löst das Problem im Allgemeinen nicht und ist ein veraltetes Modul. + +## Dinge zu tun in Ihrer Umgebung / Einrichtung + +Hier sind einige Dinge, die Sie in Ihrer Systemumgebung tun können, um die Leistung Ihrer App zu verbessern: + +- [Setze NODE_ENV auf "Produktion"](#set-node_env-to-production) +- [Stelle sicher, dass deine App automatisch neu startet](#ensure-your-app-automatically-restarts) +- [Starte deine App in einem Cluster](#run-your-app-in-a-cluster) +- [Cache-Anfrageergebnisse](#cache-request-results) +- [Lastausgleich verwenden](#use-a-load-balancer) +- [Reverse Proxy](#use-a-reverse-proxy) verwenden + +### Knoten_ENV auf "Produktion" setzen + +Die NODE_ENV Umgebungsvariable spezifiziert die Umgebung, in der eine Anwendung ausgeführt wird (normalerweise Entwicklung oder Produktion). Eines der einfachsten Dinge, die Sie tun können, um die Leistung zu verbessern, ist, NODE_ENV auf `production` zu setzen. + +Setze NODE_ENV auf "production" makes Express: + +- Cache-Ansichtsvorlagen. +- Cache-CSS-Dateien, die aus CSS-Erweiterungen generiert wurden. +- Weniger ausführliche Fehlermeldungen generieren. + +[Tests deuten an](https://www.dynatrace.com/news/blog/the-drastic-effects-of-omitting-node-env-in-your-express-js-applications/), dass dies die Leistung der App um einen Faktor von drei verbessern kann! + +Wenn Sie umweltspezifischen Code schreiben müssen, können Sie den Wert von NODE_ENV mit `process.env.NODE_ENV` überprüfen. Beachten Sie, dass die Überprüfung des Wertes einer Umgebungsvariable eine Leistungsstrafe verursacht und daher sparsam durchgeführt werden sollte. + +In der Entwicklung setzst du in der Regel Umgebungsvariablen in deiner interaktiven Shell ein, indem du `export` oder deine `.bash_profile` Datei verwendest. Aber im Allgemeinen sollten Sie das nicht auf einem Produktionsserver tun; stattdessen sollten Sie das Init-System Ihres Betriebssystems (System) verwenden. Der nächste Abschnitt enthält weitere Details zur Verwendung Ihres Init-Systems im Allgemeinen aber das Setzen von `NODE_ENV` ist so wichtig für die Leistung (und einfach zu tun), dass es hier hervorgehoben wird. + +Mit dem System verwenden Sie die `Environment` Direktive in Ihrer Einheitendatei. Zum Beispiel: + +```sh + +Environment=NODE_ENV=production +``` + +Weitere Informationen finden Sie unter [Umgebungsvariablen in systemd Units](https://www.flatcar.org/docs/latest/setup/systemd/environment-variables/). + +### Stellen Sie sicher, dass Ihre App automatisch neu gestartet wird + +In der Produktion wollen Sie nicht, dass Ihre Bewerbung offline ist. Dies bedeutet, dass Sie sicherstellen müssen, dass es sowohl neu gestartet wird, wenn die App abstürzt als auch wenn der Server selbst abstürzt. Obwohl Sie hoffen, dass keines dieser Ereignisse eintritt, müssen Sie realistischerweise beide Eventualitäten berücksichtigen von: + +- Verwendung eines Prozess-Managers, um die App (und den Knoten) neu zu starten, wenn sie abstürzt. +- Verwendung des von Ihrem Betriebssystem zur Verfügung gestellten Init-Systems, um den Prozessmanager beim Absturz des Betriebssystems neu zu starten. Es ist auch möglich, das Init-System ohne Prozessmanager zu verwenden. + +Knotenapplikationen stürzen ab, wenn sie eine nicht gefangene Ausnahme erleben. Das Wichtigste, was Sie tun müssen, ist, sicherzustellen, dass Ihre App gut getestet ist und alle Ausnahmen handhabt (siehe [Ausnahmen ordnungsgemäß behandeln](#handle-exceptions-properly) für Details). Aber als Fail-Safe setzen Sie einen Mechanismus, um sicherzustellen, dass wenn und wenn Ihre App abstürzt, automatisch neu gestartet wird. + +#### Prozessmanager verwenden + +In der Entwicklung hast du deine App einfach von der Kommandozeile aus mit `node server.js` oder etwas Ähnlichem gestartet. Aber dies in der Produktion zu tun, ist ein Rezept für eine Katastrophe. Wenn die App abstürzt, wird sie offline sein, bis Sie sie neu starten. Um sicherzustellen, dass Ihre App neu gestartet wird, wenn sie abstürzt, verwenden Sie einen Prozessmanager. Ein Prozessmanager ist ein "Container" für Anwendungen, die den Einsatz erleichtern, eine hohe Verfügbarkeit bieten und Ihnen die Verwaltung der Anwendung zur Laufzeit ermöglichen. + +Zusätzlich zum Neustart Ihrer App bei einem Absturz kann ein Prozessmanager Sie aktivieren: + +- Gewinnen Sie Einblicke in Laufzeitleistung und Ressourcenverbrauch. +- Ändern Sie die Einstellungen dynamisch, um die Leistung zu verbessern. +- Steuerung Clustering (pm2). + +Historisch war es beliebt, einen Node.js Prozessmanager wie [PM2](https://github.com/Unitech/pm2) zu verwenden. Lesen Sie deren Dokumentation, wenn Sie dies tun möchten. Wir empfehlen jedoch, Ihr Init-System für das Prozessmanagement zu verwenden. + +#### Init-System verwenden + +Die nächste Ebene der Zuverlässigkeit besteht darin, sicherzustellen, dass Ihre App beim Neustart des Servers neu gestartet wird. Systeme können aus verschiedenen Gründen immer noch heruntergehen. Um sicherzustellen, dass Ihre App neu gestartet wird, wenn der Server abstürzt, verwenden Sie das Init-System, das in Ihr Betriebssystem integriert wurde. Das heute verwendete Hauptinitsystem ist [systemd](https://wiki.debian.org/systemd). + +Es gibt zwei Möglichkeiten, Init-Systeme mit Ihrer Express-App zu verwenden: + +- Führen Sie Ihre App in einem Prozessmanager aus und installieren Sie den Prozessmanager als Service mit dem Init-System. Der Prozessmanager startet Ihre App neu, wenn die App abstürzt, und das Init-System startet den Prozessmanager beim Neustart des Betriebssystems neu. Dies ist der empfohlene Ansatz. +- Führen Sie Ihre App (und Ihren Knoten) direkt mit dem Init-System aus. Das ist etwas einfacher, aber Sie haben nicht die zusätzlichen Vorteile eines Prozessmanagers. + +##### Systemd + +Systemd ist ein Linux System und Service Manager. Die meisten großen Linux-Distributionen haben System als Standard-Init-System übernommen. + +Eine Systemd-Service-Konfigurationsdatei heißt _unit file_, mit einem Dateinamen endet in `.service`. Hier ist eine Beispiel-Einheitsdatei, um eine Knoten-App direkt zu verwalten. Ersetzen Sie die Werte in `` für Ihr System und App: + +```sh +[Unit] +Description= + +[Service] +Type=simple +ExecStart=/usr/local/bin/node +WorkingDirectory= + +User=nobody +Group=nogroup + + +Environment=NODE_ENV=production + + +LimitNOFILE=infinity + + +LimitCORE=infinity + +StandardInput=null +StandardOutput=syslog +StandardError=syslog +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +Weitere Informationen zum System finden Sie unter [systemd reference (man page)](http://www.freedesktop.org/software/systemd/man/systemd.unit). + +### Starte deine App in einem Cluster + +In einem Multi-Core-System können Sie die Leistung einer Knoten-App um ein Vielfaches erhöhen, indem Sie einen Cluster von Prozessen starten. Ein Cluster führt mehrere Instanzen der App aus, idealerweise eine Instanz auf jedem CPU-Core, wodurch die Last und Aufgaben auf die Instanzen verteilt werden. + +![Balance zwischen Anwendungsinstanzen mit der Cluster-API](/images/clustering.png) + +WICHTIG: Da die App-Instanzen als separate Prozesse laufen, teilen sie nicht den gleichen Speicherplatz. Das heißt, Objekte sind lokal für jede Instanz der App. Daher können Sie den Status im Anwendungscode nicht beibehalten. Du kannst jedoch einen Speicherdatenspeicher wie [Redis](http://redis.io/) verwenden, um Sitzungsdaten und -status zu speichern. Dieser Vorbehalt bezieht sich im Wesentlichen auf alle Formen der horizontalen Skalierung, sei es beim Clustering mit mehreren Prozessen oder mehreren physischen Servern. + +In geclusterten Apps können Worker-Prozesse individuell abstürzen, ohne den Rest der Prozesse zu beeinträchtigen. Abgesehen von den Leistungsvorteilen ist die Fehlerisolierung ein weiterer Grund, einen Cluster von App-Prozessen auszuführen. Immer wenn ein Worker-Prozess abstürzt, vergewissern Sie sich, das Ereignis zu protokollieren und einen neuen Prozess mit cluster.fork() zu erzeugen. + +#### Cluster-Modul des Knotens + +Clustering wird mit Knotens [Cluster-Modul](https://nodejs.org/api/cluster) ermöglicht. Dies ermöglicht es einem Master-Prozess, Worker-Prozesse zu generieren und eingehende Verbindungen unter den Arbeitern zu verteilen. + +#### PM2 verwenden + +Wenn Sie Ihre Anwendung mit PM2 bereitstellen, können Sie die Vorteile des Clustering _without out_ Ändern Ihres Anwendungscodes nutzen. Du solltest sicherstellen, dass deine [Anwendung zustandslos ist](https://pm2.keymetrics.io/docs/usage/specifics/#stateless-apps) zuerst , was bedeutet, dass keine lokalen Daten im Prozess gespeichert werden (wie Sessions, Websocket-Verbindungen und dergleichen). + +Wenn du eine Anwendung mit PM2 ausführst, kannst du den **Cluster-Modus** aktivieren, um ihn in einem Cluster mit einer Anzahl von Instanzen deiner Wahl auszuführen zum Beispiel die übereinstimmende Anzahl der verfügbaren CPUs. Du kannst die Anzahl der Prozesse im Cluster manuell mit dem Kommandozeilenwerkzeug `pm2` ändern, ohne die App zu stoppen. + +Um den Cluster-Modus zu aktivieren, starten Sie Ihre Anwendung so: + +```bash + +$ pm2 start npm --name my-app -i 4 -- start + +$ pm2 start npm --name my-app -i max -- start +``` + +Dies kann auch innerhalb einer PM2-Prozessdatei konfiguriert werden (`ecosystem.config. s` oder ähnlich) indem `exec_mode` auf `cluster` und `instances` auf die Anzahl der zu startenden Arbeiter gesetzt wird. + +Nach dem Ausführen kann die Anwendung so skaliert werden: + +```bash + +$ pm2 scale my-app +3 + +$ pm2 scale my-app 2 +``` + +Weitere Informationen zum Clustering mit PM2 finden Sie unter [Cluster Mode](https://pm2.keymetrics.io/docs/usage/cluster-mode/) in der PM2-Dokumentation. + +### Cache-Abfrageergebnisse + +Eine weitere Strategie zur Verbesserung der Leistung in der Produktion ist das Cache-Ergebnis von Anfragen so dass Ihre App die Operation nicht wiederholt, um dieselbe Anfrage wiederholt zu bedienen. + +Benutze einen Caching-Server wie [Varnish](https://www.varnish-cache.org/) oder [Nginx](https://blog.nginx.org/blog/nginx-caching-guide) (siehe auch [Nginx Caching](https://serversforhackers.com/nginx-caching/)) um die Geschwindigkeit und Leistung deiner App deutlich zu verbessern. + +### Lastausgleich verwenden + +Egal wie optimiert eine App ist, eine einzelne Instanz kann nur eine begrenzte Menge an Last und Traffic verwalten. Eine Möglichkeit, eine App zu skalieren, besteht darin, mehrere Instanzen davon auszuführen und den Traffic über einen Lastausgleicher zu verteilen. Das Einrichten eines Lastausgleichs kann die Leistung und Geschwindigkeit Ihrer App verbessern und es ermöglichen, mehr zu skalieren, als mit einer einzigen Instanz möglich ist. + +Ein Loadbalancer ist in der Regel ein Reverse-Proxy, der den Datenverkehr zu und von mehreren Anwendungsinstanzen und Servern regelt. Mit [Nginx](https://nginx.org/en/docs/http/load_balancing) oder [HAProxy](https://www.digitalocean.com/community/tutorials/an-introduction-to-haproxy-and-load-balancing-concepts) können Sie ganz einfach einen Lastausgleich für Ihre App einrichten. + +Bei Loadbalancing müssen Sie eventuell sicherstellen, dass Anforderungen, die mit einer bestimmten Session-ID in Verbindung stehen, mit dem Prozess verbunden sind, der sie verursacht hat. Dies ist _session_, oder _sticky sessions_, bekannt und kann durch den oben genannten Vorschlag angesprochen werden, um einen Datenspeicher wie Redis für Sitzungsdaten (je nach Anwendung) zu verwenden. Für eine Diskussion siehe [Mehrere Knoten verwenden](https://socket.io/docs/v4/using-multiple-nodes/). + +### Reverse-Proxy verwenden + +Ein Reverse Proxy sitzt vor einer Web-App und führt unterstützende Operationen auf den Anfragen aus, abgesehen von der Weiterleitung von Anfragen an die App. Es kann Fehlerseiten, Komprimierung, Caching, Servieren von Dateien und laden Balancing unter anderem. + +Die Übergabe von Aufgaben, die keine Kenntnisse des Anwendungszustands an einen Reverse Proxy erfordern, gibt Express frei, spezielle Anwendungsaufgaben durchzuführen. Aus diesem Grund wird empfohlen, Express in der Produktion hinter einem umgekehrten Proxy wie [Nginx](https://www.nginx.org/) oder [HAProxy](https://www.haproxy.org/) auszuführen. diff --git a/src/content/pages/de/advanced/best-practice-security.mdx b/src/content/pages/de/advanced/best-practice-security.mdx new file mode 100644 index 0000000000..a9967fe49c --- /dev/null +++ b/src/content/pages/de/advanced/best-practice-security.mdx @@ -0,0 +1,276 @@ +--- +title: "Beste Produktionspraktiken: Sicherheit" +description: Entdecken Sie wichtige Sicherheits-Best Practices für Express-Apps in der Produktion, einschließlich der Verwendung von TLS, Eingabe-Validierung, sichere Cookies und der Vermeidung von Schwachstellen. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Der Begriff *"production"* bezieht sich auf die Stufe im Software-Lebenszyklus, wenn eine Anwendung oder API allgemein für Endbenutzer oder Verbraucher verfügbar ist. Im Gegensatz dazu, in der *"development"* Bühne, Sie immer noch aktiv schreiben und Test-Code, und die Anwendung ist nicht offen für externen Zugriff. Die entsprechenden Systemumgebungen werden als *production* bzw. *development* Umgebungen bezeichnet. + +Entwicklungs- und Produktionsumgebungen sind in der Regel unterschiedlich aufgebaut und haben sehr unterschiedliche Anforderungen. Was in der Entwicklung gut ist, kann in der Produktion nicht akzeptabel sein. In einer Entwicklungsumgebung könnte es sein, dass Sie ausführliche Protokollierung von Fehlern zum Debuggen wünschen während das gleiche Verhalten kann zu einem Sicherheitsbedenken in einer Produktionsumgebung werden. Und in der Entwicklung müssen Sie sich keine Sorgen um Skalierbarkeit, Zuverlässigkeit und Leistung machen, während diese Bedenken in der Produktion entscheidend werden. + + + +Wenn Sie glauben, dass Sie eine Sicherheitslücke in Express entdeckt haben, lesen Sie bitte Sicherheits- +Richtlinien und Prozeduren. + + + +Best Practices für Express-Anwendungen in der Produktion beinhalten: + +* [Beste Produktionspraktiken: Sicherheit](#production-best-practices-security) + * [Overview](#overview) + * [Veraltete oder verwundbare Versionen von Express](#dont-use-deprecated-or-vulnerable-versions-of-express) + * [Benutze TLS](#use-tls) + * [Nicht auf Benutzereingabe vertrauen](#do-not-trust-user-input) + * [Verhindere offene Weiterleitungen](#prevent-open-redirects) + * [Helm verwenden](#use-helmet) + * [Fingerabdruck reduzieren](#reduce-fingerprinting) + * [Cookies sicher verwenden](#use-cookies-securely) + * [Benutze nicht den Standard-Sitzungs-Cookie Name](#dont-use-the-default-session-cookie-name) + * [Cookie Sicherheitseinstellungen setzen](#set-cookie-security-options) + * [Verhindere Brute-Force-Angriffe gegen Autorisierung](#prevent-brute-force-attacks-against-authorization) + * [Vergewissern Sie sich, dass Ihre Abhängigkeiten sicher sind](#ensure-your-dependencies-are-secure) + * [Vermeide andere bekannte Schwachstellen aus](#avoid-other-known-vulnerabilities) + * [Zusätzliche Überlegungen](#additional-considerations) + +## Veraltete oder verwundbare Versionen von Express nicht verwenden + +Express 2.x und 3.x werden nicht mehr gewartet. Sicherheits- und Leistungsprobleme in diesen Versionen werden nicht behoben. Verwenden Sie sie nicht! Wenn Sie nicht auf Version 4 umgezogen sind, folgen Sie der [Migrationsanleitung](/en/guide/migrating-4) oder überlegen Sie [Handelsunterstützungsoptionen](/en/support#commercial-support-options). + +Vergewissern Sie sich auch, dass Sie keine der verwundbaren Express-Versionen auf der [Seite für Sicherheitsupdates ] verwenden (/en/advanced/security-updates). Wenn Sie dies tun, aktualisieren Sie auf eine der stabilen Releases, vorzugsweise die neuste. + +## TLS verwenden + +Wenn Ihre App sensible Daten behandelt oder übermittelt, verwenden Sie [Transport-Layer-Sicherheit](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) um die Verbindung und die Daten zu sichern. Diese Technologie verschlüsselt Daten, bevor sie vom Client an den Server gesendet werden, und verhindert so einige häufige (und einfache) Hacks. Obwohl Ajax und POST Anfragen möglicherweise nicht sichtbar sind und im Browser "versteckt" zu sein scheinen, ihr Netzwerkverkehr ist anfällig für [Paket-Sniffing](https://en.wikipedia.org/wiki/Packet_analyzer) und [Man-in-the-middle-Angriffe](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). + +Sie können mit der Verschlüsselung Secure Socket Layer (SSL) vertraut sein. [TLS ist einfach die nächste Weiterentwicklung von SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). Mit anderen Worten: Wenn Sie SSL zuvor verwendet haben, sollten Sie ein Upgrade auf TLS in Betracht ziehen. Im Allgemeinen empfehlen wir Nginx mit TLS umzugehen. Für eine gute Referenz zum Konfigurieren von TLS auf Nginx (und anderen Servern) siehe [Empfohlene Server-Konfigurationen (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). + +Ein praktisches Werkzeug, um ein kostenloses TLS-Zertifikat zu erhalten, ist [Let's Encrypt](https://letsencrypt.org/about/), ein kostenloses und automatisiertes TLS-Zertifikat und offene Zertifizierungsstelle (CA) zur Verfügung gestellt von der [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). + +## Benutzereingabe nicht vertrauen + +Eine der wichtigsten Sicherheitsanforderungen für Webanwendungen ist die korrekte Validierung und Handhabung von Benutzereingaben. Das kommt in vielen Formen, und wir werden hier nicht alle abdecken. +Letztlich liegt die Verantwortung für die Validierung und korrekte Handhabung der Benutzereingaben, die Ihre Anwendung akzeptiert, bei Ihnen. + +### Offene Weiterleitungen verhindern + +Ein Beispiel für potenziell gefährliche Benutzereingaben ist eine *open redirect*, wo eine Anwendung akzeptiert eine URL als Benutzereingabe (oft in der URL-Abfrage, zum Beispiel "? rl=https://Beispiel. om`) und verwendet `res.redirect`um den`location\` Header und +einen 3xx Status zu setzen. + +Eine Anwendung muss überprüfen, dass sie eine Umleitung auf die eingehende URL unterstützt, um zu vermeiden, dass Benutzer an böswillige Links wie Phishing-Websites geschickt werden unter anderem Risiken. + +Hier ist ein Beispiel für die Überprüfung von URLs, bevor `res.redirect` oder `res.location`: + +```js +app.use((req, res) => { + try { + if (new Url(req. uery.url).host !== 'example.com') { + return res.status(400). nd(`Nicht unterstützte Weiterleitung zum Host: ${req.query.url}`); + } + } catch (e) { + return res. tatus(400).end(`Ungültige Url: ${req.query.url}`); + } + res.redirect(req.query.url); +}); +``` + +## Helm verwenden + +[Helmet][helmet] kann helfen, Ihre App vor einigen bekannten Web-Verwundbarkeiten zu schützen, indem Sie HTTP-Header entsprechend setzen. + +Helmet ist eine Middleware-Funktion, die sicherheitsrelevante HTTP-Antwort-Header festlegt. Helm setzt standardmäßig folgende Kopfzeilen: + +* `Content-Security-Policy`: Eine mächtige Zulassungsliste dessen, was auf deiner Seite passieren kann, die viele Angriffe mildert +* `Cross-Origin-Opener-Policy`: Hilft dabei, Ihre Seite zu isolieren +* `Cross-Origin-Resource-Policy`: Blockiert andere vom Laden deiner Ressourcen Cross-origin +* `Origin-Agent-Cluster`: Ändert die Prozess-Isolation in originalbasierte +* `Referrer-Policy`: Steuert den [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) Header +* "Strict-Transport-Sicherheit": Bedeutet Browser, HTTPS vorzuziehen +* `X-Content-Type-Optionen`: Vermeiden [MIME Sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +* `X-DNS-Prefetch-Control`: Steuert DNS-Vorabholung +* `X-Download-Optionen`: Erzwingt Downloads zu speichern (nur im Internet Explorer) +* `X-Frame-Optionen`: Legacy-Header, der [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) Angriffe mildert +* `X-Permitted-Cross-Domain-Policies`: Kontrolliert Domainübergreifendes Verhalten für Adobe-Produkte wie Acrobat +* `X-Powered-By`: Info über den Webserver. Entfernt, weil es bei einfachen Angriffen verwendet werden kann +* `X-XSS-Protection`: Legacy-Header, der versucht, [XSS-Angriffs](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), zu mildern, aber die Dinge verschlimmert, also deaktiviert Helm ihn + +Jeder Header kann konfiguriert oder deaktiviert werden. Um mehr darüber zu erfahren, gehen Sie bitte auf [seine Dokumentations-Website][helmet]. + +Helm wie jedes andere Modul installieren: + +```bash +$ npm install helmet +``` + +Dann verwenden Sie es in Ihrem Code: + +```js +// ... + +const helmet = require('helm'); +app.use(helmet()); + +// ... +``` + +## Fingerabdruck verringern + +Es kann helfen, eine zusätzliche Sicherheitsschicht zu bieten, um die Fähigkeit von Angreifern zu verringern, +die Software zu ermitteln, die ein Server benutzt bekannt als "Fingerabdruck". Obwohl es selbst kein Sicherheitsproblem ist, verbessert +die Reduzierung der Fingerabdrücke einer Anwendung seine allgemeine Sicherheitsauffassung. +Server-Software kann durch Quirks Fingerabdrücke in der Art und Weise abgerufen werden, wie sie auf bestimmte Anfragen reagiert, zum Beispiel in +den HTTP-Antwort-Headern. + +Standardmäßig sendet Express den `X-Powered-By` Antwort-Header, den Sie +deaktivieren können mit der `app.disable()` Methode: + +```js +app.disable('x-Powered by '); +``` + + + +Das Deaktivieren des `X-Powered-By-Header` hindert einen anspruchsvollen Angreifer nicht daran, +zu ermitteln, dass eine App Express ausführt. It may discourage a casual exploit, but there are other ways to +determine an app is running Express. + + + +Express sendet auch eigene formatierte "404 Not Found"-Nachrichten und Formatierungsfehler +Antwortmitteilungen. Diese können von +geändert werden [füge deinen eigenen nicht gefundenen Handler hinzu](/en/starter/faq#how-do-i-handle-404-responses) +und +[deinen eigenen Fehler zu schreiben](/en/guide/error-handling#writing-error-handlers): + +```js +// letzten app.use Aufrufe direkt vor app.listen(): + +// custom 404 +app.use((req, res, next) => { + res.status(404). end("Tut uns leid, das kann nicht gefunden werden!"); +}); + +// Custom Error handler +app. se(err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Etwas kaputt!'); +}); +``` + +## Cookies sicher verwenden + +Um sicherzustellen, dass Cookies nicht Ihre App zum Ausnutzen öffnen, verwenden Sie nicht den standardmäßigen Session-Cookie-Namen und setzen Sie die Cookie-Sicherheitsoptionen entsprechend ein. + +Es gibt zwei zentrale Middleware-Cookie-Sitzungsmodule: + +* [express-session](https://www.npmjs.com/package/express-session), die `express.session` Middleware in Express 3.x ersetzt. +* [cookie-session](https://www.npmjs.com/package/cookie-session), die die in Express 3.x integrierte Middleware `express.cookieSession` ersetzt. + +Der Hauptunterschied zwischen diesen beiden Modulen liegt darin, wie sie Cookie-Sitzungsdaten speichern. Die [express-session](https://www.npmjs.com/package/express-session) Middleware speichert Sitzungsdaten auf dem Server; sie speichert die Session-ID nur im Cookie selbst, nicht im Sitzungsdatum. Standardmäßig verwendet er Speicher im Speicher und ist nicht für eine Produktionsumgebung konzipiert. In der Produktion müssen Sie einen skalierbaren Session-Shop einrichten; siehe die Liste der [kompatiblen Session-Shops](https://github.com/expressjs/session#compatible-session-stores). + +Im Gegensatz dazu implementiert [cookie-session](https://www.npmjs.com/package/cookie-session) Middleware Cookie unterstützten Speicher: Es serialisiert die gesamte Sitzung auf das Cookie und nicht nur auf eine Sitzungsschlüssel. Verwenden Sie es nur, wenn Session-Daten relativ klein sind und leicht als primitive Werte kodiert werden (statt Objekte). Obwohl Browser mindestens 4096 Bytes pro Cookie unterstützen sollen, um sicherzustellen, dass Sie das Limit nicht überschreiten, nicht größer als 4093 Bytes pro Domain. Beachten Sie auch, dass die Cookie-Daten für den Kunden sichtbar sind, Wenn es also einen Grund gibt, es sicher oder undurchsichtig zu halten, dann könnte `express-session` eine bessere Wahl sein. + +### Nicht den Standard-Sitzungs-Cookie-Namen verwenden + +Die Verwendung des Standard-Sitzungs-Cookie-Namens kann Ihre App für Angriffe öffnen. Das Sicherheitsproblem ähnelt `X-Powered-By`: Ein potenzieller Angreifer kann es verwenden, um den Server und die Zielangriffe entsprechend zu Fingerabdruck zu verwenden. + +Um dieses Problem zu vermeiden, verwenden Sie generische Cookie-Namen; zum Beispiel [express-session](https://www.npmjs.com/package/express-session) Middleware: + +```js +const session = require('express-session'); +app.set('trust proxy', 1); // trust first proxy +app. se( + session({ + secret: 's3Cur3', + Name: 'sessionId', + }) +); +``` + +### Cookie-Sicherheitsoptionen festlegen + +Legen Sie die folgenden Cookie-Optionen fest, um die Sicherheit zu verbessern: + +* `secure` - Stellt sicher, dass der Browser das Cookie nur über HTTPS sendet. +* `httpOnly` - Stellt sicher, dass das Cookie nur über HTTP(S), nicht über Client-JavaScript, gesendet wird. Dies hilft beim Schutz vor Site-übergreifenden Skripting-Attacken. +* `domain` - gibt die Domain des Cookie an; verwenden Sie sie um sie mit der Domain des Servers zu vergleichen, auf dem die URL angefordert wird. Wenn sie übereinstimmen, überprüfen Sie als nächstes das Pfad-Attribut. +* `path` - zeigt den Pfad des Cookie; verwenden Sie ihn um mit dem Abfragepfad zu vergleichen. Wenn dies und Domäne übereinstimmen, dann senden Sie das Cookie in der Anfrage. +* `expires` - verwenden Sie, um das Ablaufdatum für persistente Cookies festzulegen. + +Hier ist ein Beispiel mit [cookie-session](https://www.npmjs.com/package/cookie-session) Middleware: + +```js +const session = require('cookie-session'); +const express = require('express'); +const app = express(); + +const expiryDate = new Date(Date. ow() + 60 * 60 * 1000); // 1 Stunde +App. se( + session({ + name: 'session', + keys: ['key1', 'key2'], + Cookie: { + Secre: true + httpOnly: true + domain: 'example. om', + Pfad: 'foo/bar', + läuft ab: expiryDate, + }, + }) +); +``` + +## Brute-Force-Angriffe gegen Autorisierung verhindern + +Stellen Sie sicher, dass Login-Endpunkte geschützt sind, um private Daten sicherer zu machen. + +Eine einfache und leistungsstarke Technik ist es, Autorisierungsversuche mit zwei Metriken zu blockieren: + +1. Die Anzahl der aufeinanderfolgenden fehlgeschlagenen Versuche mit dem gleichen Benutzernamen und der gleichen IP-Adresse. +2. Die Anzahl fehlgeschlagener Versuche einer IP-Adresse über einen längeren Zeitraum. Zum Beispiel blockieren Sie eine IP-Adresse, wenn sie 100 fehlgeschlagene Versuche an einem Tag macht. + +[rate-limiter-flexible](https://github.com/animir/node-rate-limiter-flexible) Paket stellt Werkzeuge zur Verfügung, um diese Technik einfach und schnell zu machen. Du findest [ein Beispiel für brutalen Schutz in der Dokumentation](https://github.com/animir/node-rate-limiter-flexible/wiki/Overall-example#login-endpoint-protection) + +## Stellen Sie sicher, dass Ihre Abhängigkeiten sicher sind + +Die Verwendung von npm zur Verwaltung der Abhängigkeiten Ihrer Anwendung ist mächtig und komfortabel. Aber die Pakete, die Sie verwenden, können kritische Sicherheitslücken enthalten, die auch Ihre Anwendung betreffen könnten. Die Sicherheit Ihrer App ist nur so stark wie der "schwächste Link" in Ihren Abhängigkeiten. + +Seit npm@6 überprüft npm automatisch jede Installationsanforderung. Außerdem kannst du `npm audit` verwenden, um deinen Abhängigkeitsbaum zu analysieren. + +```bash +$ npm Audit +``` + +Wenn du sicherer bleiben möchtest, bedenke [Snyk](https://snyk.io/). + +Snyk bietet sowohl ein [Kommandozeilenwerkzeug](https://www.npmjs.com/package/snyk) als auch eine [Github-Integration](https://snyk.io/docs/github), die Ihre Anwendung auf [Snyk's Open-Source-Verwundbarkeitsdatenbank] (https://snyk.io/vuln/) auf bekannte Verwundbarkeiten in Ihren Abhängigkeiten überprüft. Installieren Sie das CLI wie folgt: + +```bash +$ npm Installation -g snyk +$ cd your-app +``` + +Verwenden Sie diesen Befehl, um Ihre Anwendung auf Schwachstellen zu testen: + +```bash +$ Snyk-Test +``` + +### Vermeiden Sie andere bekannte Schwachstellen + +Halten Sie Ausschau nach [Node Security Project](https://npmjs.com/advisories) oder [Snyk](https://snyk.io/vuln/) Ankündigungen, die Express oder andere Module, die Ihre App verwendet, beeinflussen können. Im Allgemeinen sind diese Datenbanken ausgezeichnete Ressourcen für Wissen und Werkzeuge rund um die Knotensicherheit. + +Schließlich können Express-Apps—wie alle anderen Web-Apps—anfällig für eine Vielzahl webbasierter Angriffe sein. Vertrauen Sie sich mit bekannten [Web-Verwundbarkeiten](https://www.owasp.org/www-project-top-ten/) und ergreifen Sie Vorsichtsmaßnahmen, um sie zu vermeiden. + +## Zusätzliche Überlegungen + +Hier sind einige weitere Empfehlungen der ausgezeichneten [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/). Empfehlen Sie diesen Blog-Beitrag für alle Details zu diesen Empfehlungen: + +* Immer die Benutzereingabe filtern und bereinigen, um gegen Site-übergreifendes Skripting (XSS) und Injektionsangriffe zu schützen. +* Verteidigen Sie gegen SQL-Injektionsangriffe durch parametrierte Abfragen oder vorbereitete Anweisungen. +* Benutzen Sie das Open-Source [sqlmap](http://sqlmap.org/) Werkzeug, um Verwundbarkeiten in Ihrer App zu erkennen. +* Verwenden Sie die Werkzeuge [nmap](https://nmap.org/) und [sslyze](https://github.com/nabla-c0d3/sslyze) um die Konfiguration Ihrer SSL-Chiffren zu testen, Schlüssel, Neuverhandlung sowie die Gültigkeit Ihres Zertifikats. +* Verwende [safe-regex](https://www.npmjs.com/package/safe-regex), um sicherzustellen, dass deine regulären Ausdrücke nicht anfällig für [reguläre Ausdrucksverweigerung des Dienstes](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) Angriffe sind. + +[helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/de/advanced/healthcheck-graceful-shutdown.md b/src/content/pages/de/advanced/healthcheck-graceful-shutdown.md new file mode 100644 index 0000000000..df8006c126 --- /dev/null +++ b/src/content/pages/de/advanced/healthcheck-graceful-shutdown.md @@ -0,0 +1,28 @@ +--- +title: Gesundheitschecks und anmutiges Herunterfahren +description: Erfahren Sie, wie Sie Gesundheitschecks und anmutiges Herunterfahren in Express-Apps implementieren können, um die Zuverlässigkeit zu verbessern, den Einsatz zu verwalten und sich mit Lastausgleichern wie Kubernetes zu integrieren. +--- + +## Angemessenes Herunterfahren + +Wenn Sie eine neue Version Ihrer Anwendung bereitstellen, müssen Sie die vorherige Version ersetzen. Der von Ihnen verwendete Prozessmanager sendet zuerst ein SIGTERM-Signal an die Anwendung, um zu benachrichtigen, dass es beendet wird. Sobald die Anwendung dieses Signal erhält, sollte sie aufhören, neue Anfragen anzunehmen, alle laufenden Anfragen zu beenden, die verwendeten Ressourcen aufräumen, einschließlich Datenbankverbindungen und Dateisperren dann beenden. + +### Beispiel + +```js +const server = app.listen(port); + +process.on('SIGTERM', () => { + debug('SIGTERM signal received: closing HTTP server'); + server.close(() => { + debug('HTTP server closed'); + }); +}); +``` + +## Gesundheitschecks + +Ein Lastausgleicher verwendet Gesundheitsprüfungen, um festzustellen, ob eine Anwendungsinstanz gesund ist und Anfragen annehmen kann. Zum Beispiel [Kubernetes hat zwei Gesundheitschecke](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/): + +- 'liveness', das bestimmt, wann ein Container neu gestartet werden soll. +- `readiness`, das bestimmt, wann ein Container bereit ist, den Verkehr zu akzeptieren. Wenn ein Pod nicht bereit ist, wird er aus den Lastausgleichern entfernt. diff --git a/src/content/pages/de/advanced/security-updates.mdx b/src/content/pages/de/advanced/security-updates.mdx new file mode 100644 index 0000000000..08350bea85 --- /dev/null +++ b/src/content/pages/de/advanced/security-updates.mdx @@ -0,0 +1,87 @@ +--- +title: Sicherheitsupdates +description: Überprüfen Sie die neuesten Sicherheitsupdates und Patches für Express.js, einschließlich detaillierter Verwundbarkeitslisten für verschiedene Versionen, um eine sichere Anwendung zu pflegen. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Verwundbarkeiten von Node.js wirken sich direkt auf Express aus. Daher achte auf Node.js +Verwundbarkeit und stelle sicher, dass du die neueste +stabile Version von Node.js verwendest. + + + +Die folgende Liste listet die Express Verwundbarkeiten auf, die in der angegebenen Versionsaktualisierung behoben wurden. + + + +Wenn Sie glauben, dass Sie eine Sicherheitslücke in Express entdeckt haben, lesen Sie bitte Sicherheits- +Richtlinien und Prozeduren. + + + +## 4,x + +* 4.21.2 + * Die Abhängigkeit `path-to-regexp` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +* 4.21.1 + * Die Abhängigkeit `cookie` wurde aktualisiert, um eine [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x) zu adressieren. Dies kann deine Anwendung beeinflussen, wenn du `res.cookie` verwendest. +* 4.20.0 + * XSS-Verwundbarkeit in `res.redirect` behoben ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + * Die Abhängigkeit `serve-static` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/advisories/GHSA-cm22-4g7w-348p). + * Die Abhängigkeit `send` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + * Die Abhängigkeit `path-to-regexp` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + * Die Abhängigkeit `body-parser` wurde aktualisiert, um einen [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), dies kann deine Anwendung beeinflussen, wenn du url enconding aktiviert hast. +* 4.19.0, 4.19.1 + * Behoben der offenen Weiterleitungsverwundbarkeit in `res.location` und `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +* 4.17.3 + * Die Abhängigkeit `qs` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/advisories/GHSA-hrpp-h998-j3pp). Dies kann Ihre Anwendung beeinflussen, wenn die folgenden APIs verwendet werden: `req.query`, `req.body`, `req.param`. +* 4.16.0 + * Die Abhängigkeit `forwarded` wurde aktualisiert, um eine [vulnerability]Adresse zu senden (https://npmjs.com/advisories/527). Dies kann Ihre Anwendung beeinflussen, wenn die folgenden APIs verwendet werden: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + * Die Abhängigkeit `mime` wurde aktualisiert, um eine [vulnerability](https://npmjs.com/advisories/535), aber dieses Problem wirkt sich nicht auf Express aus. + * Die Abhängigkeit `send` wurde aktualisiert, um einen Schutz gegen eine [Node.js 8.5.0 Verwundbarkeit](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/) zu bieten. Dies wirkt sich nur auf die Ausführung von Express auf der speziellen Node.js Version 8.5.0 aus. +* 4.15.5 + * Die Abhängigkeit `debug` wurde aktualisiert, um eine [vulnerability](https://snyk.io/vuln/npm:debug:20170905), aber dieses Problem wirkt sich nicht auf Express aus. + * Die Abhängigkeit `fresh` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://npmjs.com/advisories/526). Dies wird deine Anwendung beeinflussen, wenn die folgenden APIs verwendet werden: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. +* 4.15.3 + * Die Abhängigkeit `ms` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://snyk.io/vuln/npm:ms:20170412). Dies kann Ihre Anwendung beeinflussen, wenn die nicht vertrauenswürdige Eingabe an die Option `maxAge` in der folgenden APIs übergeben wird: `express.static`, `res.sendfile` und `res.sendFile`. +* 4.15.2 + * Die Abhängigkeit `qs` wurde aktualisiert, um eine [vulnerability](https://snyk.io/vuln/npm:qs:20170213), aber dieses Problem wirkt sich nicht auf Express aus. Die Aktualisierung auf 4.15.2 ist eine gute Praxis, aber nicht erforderlich, um die Verwundbarkeit zu beheben. +* 4.11.1 + * Verwundbarkeit der Root-Pfad-Offenlegung in `express.static`, `res.sendfile` und `res.sendFile` behoben +* 4.10.7 + * Behoben der offenen Weiterleitungsverwundbarkeit in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 4.8.8 + * Fehlerbehebung von Verzeichnisüberschreitungen in `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +* 4.8.4 + * Node.js 0.10 kann `fd`s in bestimmten Situationen lecken, die `express.static` und `res.sendfile` betreffen. Schädliche Anfragen könnten `fd`s zu Leck führen und letztendlich zu `EMFILE` Fehlern und Serverunreaktion. +* 4.8.0 + * Sparse Arrays mit extrem hohen Indizes im Query-String könnten dazu führen, dass der Prozess aus dem Speicher geht und der Server abstürzt. + * Extrem verschachtelte Query-String-Objekte könnten dazu führen, dass der Prozess blockiert und der Server vorübergehend nicht reagiert. + +## 3,x + + +**Express 3.x IST END-OF-OF-LEBEN UND KEINE LIEFERANTEN** + +Bekannte und unbekannte Sicherheits- und Leistungsprobleme in 3.x wurden seit dem letzten Update (1. August 2015) nicht behoben. Es wird dringend empfohlen, die neueste Version von Express zu verwenden. + +Wenn du nicht in der Lage bist nach 3.x zu aktualisieren, erwäge bitte [Kommerzielle Support-Optionen](/en/support#commercial-support-options). + + + +* 3.19.1 + * Verwundbarkeit der Root-Pfad-Offenlegung in `express.static`, `res.sendfile` und `res.sendFile` behoben +* 3.19.0 + * Behoben der offenen Weiterleitungsverwundbarkeit in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 3.16.10 + * Fehlerbehebung von Verzeichnisüberschreitungen in `express.static`. +* 3.16.6 + * Node.js 0.10 kann `fd`s in bestimmten Situationen lecken, die `express.static` und `res.sendfile` betreffen. Schädliche Anfragen könnten `fd`s zu Leck führen und letztendlich zu `EMFILE` Fehlern und Serverunreaktion. +* 3.16.0 + * Sparse Arrays, die extrem hohe Indizes im Query-String haben, könnten dazu führen, dass der Prozess aus dem Speicher geht und den Server abstürzt. + * Extrem verschachtelte Query-String-Objekte könnten dazu führen, dass der Prozess blockiert und der Server vorübergehend nicht reagiert. +* 3.3.0 + * Die 404-Reaktion eines nicht unterstützten Methodenversuchs war anfällig für Site-übergreifende Skripting-Attacken. diff --git a/src/content/pages/de/guide/database-integration.mdx b/src/content/pages/de/guide/database-integration.mdx new file mode 100644 index 0000000000..53dacff31d --- /dev/null +++ b/src/content/pages/de/guide/database-integration.mdx @@ -0,0 +1,503 @@ +--- +title: Datenbankintegration +description: Erfahren Sie, wie Sie verschiedene Datenbanken mit Express.js Anwendungen integrieren können, einschließlich der Einrichtung von Beispielen für MongoDB, MySQL, PostgreSQL und mehr. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Hinzufügen der Möglichkeit, Datenbanken mit Express-Apps zu verbinden, ist nur eine Frage des Laden eines geeigneten Node.js Treibers für die Datenbank in Ihrer App. Dieses Dokument erklärt kurz wie Sie einige der beliebtesten Node.js-Module für Datenbanksysteme in Ihrer Express-App hinzufügen und nutzen: + +* [Cassandra](#cassandra) +* [Couchbase](#couchbase) +* [CouchDB](#couchdb) +* [LevelDB](#leveldb) +* [MySQL](#mysql) +* [MongoDB](#mongodb) +* [Neo4j](#neo4j) +* [Oracle](#oracle) +* [PostgreSQL](#postgresql) +* [Redis](#redis) +* [SQL Server](#sql-server) +* [SQLite](#sqlite) +* [Elasticsearch](#elasticsearch) + + + +Diese Datenbanktreiber sind unter vielen verfügbar. Für andere Optionen suchen Sie auf der +[npm](https://www.npmjs.com/) Seite. + + + +## Cassandra + +**Modul**: [cassandra-driver](https://github.com/datastax/nodejs-driver) + +### Installation + +```bash +$ npm install cassandra-driver +``` + +### Beispiel + +```js +const cassandra = require('cassandra-driver'); +const client = new cassandra.Client({ contactPoints: ['localhost'] }); + +client. xecute('select key from system.local', (err, result) => { + if (err) throw err; + console.log(result.rows[0]); +}); +``` + +## Couchbase + +**Modul**: [couchnode](https://github.com/couchbase/couchnode) + +### Installation + +```bash +$ npm install couchbase +``` + +### Beispiel + +```js +const couchbase = require('couchbase'); +const bucket = new couchbase.Cluster('http://localhost:8091').openBucket('bucketName'); + +// Ein Dokument zu einem Bucket +bucket hinzufügen. nsert('document-key', { name: 'Matt', shoeSize: 13 }, (err, result) => { + if (err) { + console. og(err); + } else { + console. og(result); + } +}); + +// alle Dokumente mit Schuhgröße 13 +const n1ql = 'SELECT d. FROM `bucketName` d WHERE shoeSize = $1'; +const query = N1qlQuery. romString(n1ql); +bucket.query(query, [13], (err, result) => { + if (err) { + console. og(err); + } else { + console.log(result); + } +}); +``` + +## CouchDB + +**Modul**: [nano](https://github.com/dscape/nano) + +### Installation + +```bash +$ npm install nano +``` + +### Beispiel + +```js +const nano = require('nano')('http://localhost:5984'); +nano.db.create('books'); +const books = nano.db. se('books'); + +// Fügen Sie ein Buchdokument in die Datenbank +Bücher ein. nsert({ name: 'The Art of War' }, null, (err, body) => { + if (err) { + console. og(err); + } else { + console. og(body); + } +}); + +// Eine Liste aller Bücher +herunterladen. ist((err, body) => { + if (err) { + console. og(err); + } else { + console.log(body.rows); + } +}); +``` + +## LevelDB + +**Modul**: [levelup](https://github.com/rvagg/node-levelup) + +### Installation + +```bash +$ npm Level Level Level down +``` + +### Beispiel + +```js +const levelup = require('levelup'); +const db = levelup('./mydb'); + +db. ut('name', 'LevelUP', (err) => { + if (err) return console.log('Ooops!', err); + + db. et('name', (err, value) => { + if (err) return console. og('Ooops!', err); + + console.log(`name=${value}`); + }); +}); +``` + +## MySQL + +**Modul**: [mysql](https://github.com/felixge/node-mysql/) + +### Installation + +```bash +$ npm install mysql +``` + +### Beispiel + +```js +const mysql = require('mysql'); +const connection = mysql. reateConnection({ + host: 'localhost', + user: 'dbuser', + Passwort: 's3kreee7', + Datenbank: 'my_db', +}); + +Verbindung. onnect(); + +connection.query('SELECT 1 + 1 AS solution', (err, Zeilen, Felder) => { + if (err) throw err; + + console. og('Die Lösung ist: ', Zeilen[0].solution); +}); + +connection.end(); +``` + +## MongoDB + +**Modul**: [mongodb](https://github.com/mongodb/node-mongodb-native) + +### Installation + +```bash +$ npm install mongodb +``` + +### Beispiel (v2.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { + if (err) throw err; + + db. ollection('Säuge') + .find() + . oArray((err, result) => { + if (err) throw err; + + console. og(Ergebnis); + }); +}); +``` + +### Beispiel (v3.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, client) => { + if (err) throw err; + + const db = client. b('animals'); + + db.collection('Säugetier') + .find() + . oArray((err, result) => { + if (err) throw err; + + console. og(Ergebnis); + }); +}); +``` + +Wenn du einen Objektmodelltreiber für MongoDB möchtest, schau dir [Mongoose]an (https://github.com/LearnBoost/mongoose). + +## Neo4j + +**Modul**: [neo4j-driver](https://github.com/neo4j/neo4j-javascript-driver) + +### Installation + +```bash +$ npm install neo4j-driver +``` + +### Beispiel + +```js +const neo4j = require('neo4j-driver'); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth. asic('neo4j', 'letmein')); + +const session = driver.session(); + +session.readTransaction((tx) => { + return tx + . un('MATCH (n) RETURN count(n) AS count') + .then((res) => { + console.log(res.records[0]. et('count')); + }) + .catch((error) => { + Konsole. og(error); + }); +}); +``` + +## Jürgen + +**Modul**: [oracledb](https://github.com/oracle/node-oracledb) + +### Installation + +HINWEIS: [Siehe die Installationsvoraussetzungen](https://github.com/oracle/node-oracledb#-installation). + +```bash +$ npm oracledb installieren +``` + +### Beispiel + +```js +const oracledb = require('oracledb'); +const config = { + user: '', + Passwort: '', + connectString: 'localhost:1521/orcl', +}; + +async function getEmployee(empId) { + let conn; + + try { + conn = wait oracledb. etConnection(config); + + const result = warten conn. xecute('wählen Sie * von Mitarbeitern, bei denen staffe_id = :id', [empId]); + + Konsole. og(result.rows[0]); + } catch (err) { + Konsole. og('Ouch! , Fehler); + } Endlich { + if (conn) { + // conn assignment worked, müssen Sie + warten Konn. lose(); + } + } +} + +getEmployee(101); +``` + +## PostgreSQL + +**Modul**: [pg-promise](https://github.com/vitaly-t/pg-promise) + +### Installation + +```bash +$ npm install pg-promise +``` + +### Beispiel + +```js +const pgp = require('pg-promise')(/* options */); +const db = pgp('postgres://username:password@host:port/database'); + +db.one('SELECT $1 AS value', 123) + . hen((data) => { + console.log('DATA:', data.value); + }) + . atch((error) => { + console.log('ERROR:', error); +}); +``` + +## Redis + +**Modul**: [redis](https://github.com/mranney/node_redis) + +### Installation + +```bash +$ npm install redis +``` + +### Beispiel + +```js +const redis = require('redis'); +const client = redis.createClient(); + +client.on('error', (err) => { + console.log(`Error ${err}`); +}); + +client. et('string key', 'string val', redis.print); +client.hset('hash key', 'hashtest 1', 'some value', redis.print); +client. set(['hash key', 'hashtest 2', 'some other value'], redis.print); + +client. keys('hash key', (err, replies) => { + console.log(`${replies.length} Antworten:`); + + Antworten. orEach((reply, i) => { + Konsole. og(` ${i}: ${reply}`); + }); + + client.quit(); +}); +``` + +## SQL-Server + +**Modul**: [tedious](https://github.com/tediousjs/tedious) + +### Installation + +```bash +$ npm install tedious +``` + +### Beispiel + +```js +const Connection = require('tedious').Connection; +const Request = require('tedious'). quest; + +const config = { + server: 'localhost', + Authentifizierung: { + type: 'default', + Optionen: { + userName: 'your_username', // Aktualisiere mich + Passwort: 'your_password', // Aktualisiere mich + }, + }, +}; + +const connection = new Connection(config); + +Verbindung. n('connect', (err) => { + if (err) { + console. og(err); + } else { + executeStatement(); + } +}); + +Funktion executeStatement() { + request = new Request("select 123, 'Hallo world'", (err, rowCount) => { + if (err) { + console. og(err); + } else { + console. og(`${rowCount} Zeilen`); + } + Verbindung. lose(); + }); + + request.on('row', (columns) => { + columns. orEach((column) => { + if (column.value === null) { + console. og('NULL'); + } else { + console.log(column. alue); + } + }); + }); + + connection.execSql(request); +} +``` + +## SQLite + +**Modul**: [sqlite3](https://github.com/mapbox/node-sqlite3) + +### Installation + +```bash +$ npm install sqlite3 +``` + +### Beispiel + +```js +const sqlite3 = require('sqlite3').verbose(); +const db = new sqlite3.Database(':memory:'); + +db.serialize(() => { + db. un('CREATE TABLE lorem (info TEXT)'); + const stmt = db. repare('INSERT INTO lorem VALUES (?)'); + + für (let i = 0; i < 10; i++) { + stmt. un(`Ipsum ${i}`); + } + + stmt.finalize(); + + db. ach('SELECT rowid AS id, info FROM lorem', (err, row) => { + Konsole. og(`${row.id}: ${row.info}`); + }); +}); + +db.close(); +``` + +## Elasticsearch + +**Modul**: [elasticsearch](https://github.com/elastic/elasticsearch-js) + +### Installation + +```bash +$ npm elasticsearch installieren +``` + +### Beispiel + +```js +const elasticsearch = require('elasticsearch'); +const client = elasticsearch.Client({ + host: 'localhost:9200', +}); + +client + . earch({ + index: 'books', + type: 'book', + body: { + query: { + multi_match: { + query: 'express js', + Felder: ['title', 'description'], + }, + }, + }, + }) + . hen( + (Antwort) => { + const hits = response.hits. its; + }, + (error) => { + console. race(error.message); + } +); +``` diff --git a/src/content/pages/de/guide/migrating-4.mdx b/src/content/pages/de/guide/migrating-4.mdx new file mode 100644 index 0000000000..0c04eb75e3 --- /dev/null +++ b/src/content/pages/de/guide/migrating-4.mdx @@ -0,0 +1,661 @@ +--- +title: Umzug nach Express 4 +description: Eine Anleitung zur Migration Ihrer Express.js Anwendungen von Version 3 auf 4, die Änderungen in Middleware, Routing und wie Sie Ihre Codebase effektiv aktualisieren können. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express 4 ist ein brillanter Wechsel von Express 3. Das bedeutet, dass eine bestehende Express 3-App *nicht* funktioniert, wenn Sie die Express-Version in ihren Abhängigkeiten aktualisieren. + +Dieser Artikel Covers: + + + +## Änderungen in Express 4 + +Es gibt mehrere bedeutende Änderungen in Express 4: + + + +Siehe auch: + +* [Neue Features in 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +* [Migration von 3.x auf 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) + +### Änderungen am Express-Kern- und Middleware-System + +Express 4 hängt nicht mehr von Verbindung ab und entfernt alle eingebauten +Middleware aus seinem Kern, mit Ausnahme der `express.static` Funktion. Das bedeutet, dass +Express jetzt ein unabhängiges Routing- und Middleware-Web-Framework ist und +Express-Versionierung und Releases sind nicht von Middleware-Updates betroffen. + +Ohne integrierte Middleware müssen Sie explizit alle +Middleware hinzufügen, die für den Betrieb Ihrer App erforderlich ist. Folgen Sie einfach diesen Schritten: + +1. Modul installieren: `npm install --save ` +2. Benötige in deiner App das Modul: `require('module-name')` +3. Verwenden Sie das Modul entsprechend seiner Dokumentation: `app.use( ... )` + +Die folgende Tabelle listet Express 3 Middleware und ihre Amtskollegen in Express 4 auf. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Express 3Express 4
+ express.bodyParser + + Körper-Parser + + Multer +
+ express .compress + + Komprimierung +
+ express.cookieSession + + Cookie-Sitzung +
+ express.cookieParser + + Cookie-Parser +
+ express.logger + + Morgan +
+ express.session + + Express-Session +
+ express.favicon + + Servierfavicon +
+ express.responseTime + + Antwortzeit +
+ express.errorHandler + + errorhandler +
+ express.methodOverride + + Methodenüberschreibung +
+ express.timeout + + Verbindungs-Timeout +
+ express.vhost + + vhost +
+ express.csrf + + csurf +
+ express.directory + + Servierindex +
+ express.static + + Servierstatische +
+ +Hier ist die [vollständige Liste](https://github.com/senchalabs/connect#middleware) von Express 4 Middleware. + +In den meisten Fällen können Sie einfach die alte Version 3 Middleware durch +dessen Express 4 Gegenstück ersetzen. Details hierzu finden Sie in der Moduldokumentation in +GitHub. + +#### `app.use` akzeptiert Parameter + +In Version 4 können Sie mit einem Variablen-Parameter den Pfad definieren, in dem Middleware-Funktionen geladen werden, dann den Wert des Parameters aus dem Route-Handler lesen. +Zum Beispiel: + +```js +app.use('/book/:id', (req, res, next) => { + console.log('ID:', req.params.id); + next(); +}); +``` + +### Das Routingsystem + +Apps laden nun implizit Routing Middleware damit Sie sich keine +Sorgen mehr darüber machen müssen, in welcher Reihenfolge Middleware in Bezug auf +der `router` Middleware geladen wird. + +Die Art und Weise, wie Sie Routen definieren, ist unverändert, aber das Routensystem hat zwei +neue Funktionen, um Ihre Routen zu organisieren: + +* Eine neue Methode, `app.route()`, um verkettete Routenhandler für einen Routenpfad zu erstellen. +* Eine neue Klasse, `express.Router`, um modulare montierbare Routenhandler zu erstellen. + +#### `app.route()` Methode + +Die neue Methode `app.route()` ermöglicht es dir, verkettete Routenhandler +für einen Routenpfad zu erstellen. Da der Weg an einem einzigen Ort angegeben ist, ist die Schaffung modularer Routen hilfreich, ebenso wie die Reduzierung von Redundanz und Typos. Weitere +Informationen über Routen finden Sie unter [`Router()` Dokumentation](/en/4x/api#router). + +Hier ist ein Beispiel für verkettete Routenhandler, die durch die Funktion `app.route()` definiert werden. + +```js +app + .route('/book') + .get((req, res) => { + res. end('Holt ein zufälliges Buch'); + }) + . ost(req, res) => { + res.send('Add a book'); + }) + . ut((req, res) => { + res.send('Buch aktualisieren'); +}); +``` + +#### `express.Router` Klasse + +Die andere Funktion, die hilft, Routen zu organisieren, ist eine neue Klasse, +`express.Router`, die Sie verwenden können, um modulare montierbare +Routenhandler zu erstellen. Eine `Router`-Instanz ist ein komplettes Middleware- und +\-Routing-System. Aus diesem Grund wird sie oft als "Mini-App" bezeichnet. + +Das folgende Beispiel erzeugt einen Router als Modul, lädt Middleware in +, definiert einige Routen und mountet sie auf einem Pfad in der Hauptanwendung. + +Erstelle zum Beispiel eine Router-Datei namens `birds.js` im App-Verzeichnis, +mit folgendem Inhalt: + +```js +var express = require('express'); +var router = express.Router(); + +// Middleware spezifisch für diesen +Router. se(req, res, next) => { + console.log('Time: ', Datum. ow()); + next(); +}); +// die Startseite Route +definieren. et('/', (req, res) => { + res.send('Birds home page'); +}); +// über Route +definieren. et('/about', (req, res) => { + res.send('Über Vögel'); +}); + +module.exports = router; +``` + +Laden Sie dann das Router-Modul in der App: + +```js +var birds = require('./birds'); + +// ... + +app.use('/birds', Vögel); +``` + +Die App wird nun in der Lage sein, Anfragen an die `/birds` und +`/birds/about` Pfade zu bearbeiten, und ruft die "timeLog" +Middleware auf, die spezifisch für die Route ist. + +### Andere Änderungen + +Die folgende Tabelle listet weitere kleine, aber wichtige Änderungen in Express 4 auf: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ObjektBeschreibung
Node.jsExpress 4 benötigt Node.js 0.10.x oder höher und hat die Unterstützung für Node.js 0.8.x fallen gelassen.
`http.createServer()` + Das `http` Modul wird nicht mehr benötigt, außer du musst direkt mit ihm + (socket.io/SPDY/HTTPS) arbeiten. Die App kann über die Funktion `app.listen()` gestartet werden. +
`app.configure()` + Die Funktion `app.configure()` wurde entfernt. Benutze die Funktion `process.env.NODE_ENV` oder + `app.get('env')` um die Umgebung zu erkennen und die App entsprechend zu konfigurieren. +
`json spaces` + Die Eigenschaft `json spaces` ist standardmäßig in Express 4 deaktiviert. +
`req.accepted()` + Benutze `req.accepts()`, `req.acceptsEncodings()`, `req.acceptsCharsets()` und + `req.acceptsLanguages()`. +
`res.location()`Es werden keine relativen URLs mehr aufgelöst.
`req.params`War ein Array; jetzt ein Objekt.
`res.locals`War eine Funktion; jetzt ein Objekt.
`res.headerSent`In `res.headersSent` geändert.
`app.route`Jetzt als `app.mountpath` verfügbar.
`res.on('header')`Entfernt.
`res.charset`Entfernt.
`res.setHeader('Set-Cookie', val)` + Die Funktionalität ist nun auf das Setzen des grundlegenden Cookie-Wertes beschränkt. Benutze `res.cookie()` für hinzugefügte + Funktionalität. +
+ +## Beispiel-App-Migration + +Hier ist ein Beispiel für die Migration einer Express-3-Anwendung auf Express 4. +Die Dateien von Interesse sind `app.js` und `package.json`. + +### Version 3 App + +#### `app.js` + +Betrachten Sie eine Express v.3 Anwendung mit der folgenden `app.js` Datei: + +```js +var express = require('express '); +var routes = require('./routes'); +var user = require('. routes/user'); +var http = require('http'); +var path = require('path'); + +var app = express(); + +// alle Umgebungen +app. et('port', process.env.PORT || 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(express.favicon()); +app.use(express.logger('dev')); +app.use(express.methodOverride()); +app.use(express. ession({ secret: 'your secret here' })); +app.use(express.bodyParser()); +app.use(app.router); +app.use(express. tatic(path.join(__dirname, 'public'))); + +// Entwicklung nur +if (app.get('env') === 'development') { + app. se(express.errorHandler()); +} + +app.get('/', routes.index); +app.get('/users', user.list); + +http. reateServer(app).listen(app.get('port'), () => { + console.log('Express Server, der auf Port ' + app.get('port')); +}); +``` + +#### "package.json" + +The accompanying version 3 `package.json` file might look +something like this: + +```json +{ + "name": "application-name", + "version": "0.0. ", + "private": true + "scripts": { + "start": "node app. s" + }, + "dependencies": { + "express": "3. 2.0", + "Pug": "*" + } +} +``` + +### Verarbeiten + +Beginnen Sie den Migrationsprozess, indem Sie die benötigte Middleware für die +Express 4 App installieren und Express und Pug mit folgendem Befehl auf ihre jeweils neueste +Version aktualisieren: + +```bash +$ npm installieren serve-favicon morgan method-override express-session body-parser multer errorhandler express@latest pug@latest --save +``` + +Folgende Änderungen an `app.js` vornehmen: + +1. Die integrierten Express-Middleware-Funktionen `express.favicon`, + `express.logger`, `express.methodOverride`, + `express.session`, `express.bodyParser` und + `express.errorHandler` sind nicht mehr verfügbar auf dem + `express` Objekt. Sie müssen ihre Alternativen + manuell installieren und in der App laden. + +2. Du musst die `app.router` Funktion nicht mehr laden. + Es ist kein gültiges Express 4 App-Objekt, also entferne den + `app.use(app.router);` Code. + +3. Stellen Sie sicher, dass die Middleware-Funktionen in der richtigen Reihenfolge geladen werden - laden Sie `errorHandler` nach dem Laden der App-Routen. + +### Version 4 App + +#### "package.json" + +Das Ausführen des obigen `npm` Befehls wird `package.json` wie folgt aktualisieren: + +```json +{ + "name": "application-name", + "version": "0.0. ", + "private": true + "scripts": { + "start": "node app. s" + }, + "dependencies": { + "body-parser": "^1.5.2", + "errorhandler": "^1.1. ", + "express ": "^4.8.0", + "express-session": "^1. .2", + "pug": "^2.0.0", + "method-override": "^2. .2", + "morgan": "^1.2.2", + "multer": "^0.1. ", + "serve-favicon": "^2.0.1" + } +} +``` + +#### `app.js` + +Entferne dann ungültigen Code, lade die benötigte Middleware und führe bei Bedarf andere +Änderungen durch. Die `app.js` Datei wird folgendermaßen aussehen: + +```js +var http = require('http'); +var express = require('express'); +var routes = require('./routes'); +var user = require('. routes/user'); +var path = require('path'); + +var favicon = require('serve-favicon'); +var logger = require('morgan'); +var methodOverride = require('method-override'); +var session = require('express-session'); +var bodyParser = require('body-parser'); +var multer = require('multer'); +var errorHandler = require('errorhandler'); + +var app = express(); + +// alle Umgebungen +app. et('port', process.env.PORT || 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(favicon(path.join(__dirname, '/public/favicon.ico'))); +app.use(logger('dev')); +app. se(methodOverride()); +app. se( + session({ + resave: true, + saveUninitialized: true + Geheimnis: 'uwotm8', + }) +); +App. se(bodyParser.json()); +app.use(bodyParser.urlencoded({ extended: true })); +app.use(multer()); +app.use(express.static(path.join(__dirname, 'public'))); + +app.get('/', routes. ndex); +app.get('/users', user.list); + +// Fehler beim Umgang mit Middleware sollten nach dem Laden der Routen +geladen werden, wenn (app. et('env') === 'development') { + app. se(errorHandler()); +} + +var server = http.createServer(app); +server.listen(app. et('port'), () => { + console.log('Express Server, der auf Port ' + app.get('port')); +}); +``` + + +Wenn du nicht direkt mit dem `http` Modul (socket.io/SPDY/HTTPS) arbeiten musst, ist das Laden nicht erforderlich, und die App kann einfach auf diese Weise gestartet werden: + +```js +app.listen(app.get('port'), () => { + console.log('Express Server, der auf Port ' + app.get('port')); +}); +``` + + + +### App ausführen + +Der Migrationsprozess ist abgeschlossen und die App ist nun eine +Express 4 App. Um die App zu bestätigen, starten Sie die App mit dem folgenden Befehl: + +```bash +$ Knoten . +``` + +Laden Sie [http://localhost:3000](http://localhost:3000) +und sehen Sie die Startseite von Express 4 an. + +## Upgrade auf den Express 4 App-Generator + +Das Kommandozeilen-Werkzeug, um eine Express-App zu generieren, ist immer noch +`Express`, aber um auf die neue Version zu aktualisieren Sie müssen +den Express 3 App-Generator deinstallieren und dann den neuen +`express-generator` installieren. + +### Installiere + +Wenn Sie bereits den Express 3 App-Generator auf Ihrem System installiert haben, +müssen Sie ihn deinstallieren: + +```bash +$ npm Deinstallation -g Express +``` + +Depending on how your file and directory privileges are configured, +you might need to run this command with `sudo`. + +Jetzt den neuen Generator installieren: + +```bash +$ npm Installation -g express-generator +``` + +Depending on how your file and directory privileges are configured, +you might need to run this command with `sudo`. + +Jetzt wird der Befehl `Express` auf Ihrem System auf den +Express 4 Generator aktualisiert. + +### Änderungen am App-Generator + +Befehlsoptionen und -verwendung bleiben weitgehend gleich, mit den folgenden Ausnahmen: + +* Die Option `--sessions` wurde entfernt. +* Die `--jshtml` Option wurde entfernt. +* `--hogan` Option hinzugefügt, um [Hogan.js]zu unterstützen (http://twitter.github.io/hogan.js/). + +### Beispiel + +Führen Sie den folgenden Befehl aus, um eine Express 4 App zu erstellen: + +```bash +$ Express App 4 +``` + +Wenn du dir den Inhalt der `app4/app.js` Datei anschaust, wirst du +bemerken, dass alle Middleware-Funktionen (außer `express. tatic`), die für +benötigt werden, wird die App als unabhängige Module geladen, und die `router` Middleware +nicht mehr explizit in der App geladen wird. + +Du wirst auch bemerken, dass die `app.js` Datei jetzt ein Knoten ist. s Modul im Gegensatz zu der Standalone-App, die vom alten Generator erzeugt wurde. + +Nach der Installation der Abhängigkeiten starten Sie die App mit dem folgenden Befehl: + +```bash +$ npm Start +``` + +Wenn du das `npm start`-Skript im `package betrachtest. son-Datei, +wirst du bemerken, dass der eigentliche Befehl, der die App startet, +`node ist. bin/www`, die zuvor `node app.js\` +in Express 3 war. + +Because the `app.js` file that was generated by the Express 4 generator +is now a Node.js module, it can no longer be started independently as an app +(unless you modify the code). Das Modul muss in einer Node.js-Datei +geladen und über die Node.js-Datei gestartet werden. Die Node.js Datei ist in diesem Fall `./bin/www` +. + +Weder das `bin` Verzeichnis noch die erweiterungslose `www` +Datei ist zwingend erforderlich, um eine Express-App zu erstellen oder die App zu starten. They are +just suggestions made by the generator, so feel free to modify them to suit your +needs. + +Um das `www`-Verzeichnis loszuwerden und die Dinge auf die "Express 3 Wege" zu halten, lösche +die Zeile, die `module. xports = app;` am Ende der +`app.js` Datei einfügen und den folgenden Code dort einfügen: + +```js +app.set('port', process.env.PORT || 3000); + +var server = app.listen(app.get('port'), () => { + debug('Express Server, der auf Port '+ server.address().port); +}); +``` + +Stelle sicher, dass du das `debug` Modul oben in der `app.js` Datei unter Verwendung des folgenden Codes lädst: + +```js +var debug = require('debug')('app4'); +``` + +Als nächstes ändere `"start": "node ./bin/www"` in der Datei `package.json` zu `"start": "node app.js"`. + +Du hast nun die Funktionalität von `./bin/www` zurück auf +`app.js` verschoben. Diese Änderung wird nicht empfohlen, aber die Übung hilft dir +zu verstehen, wie das `. bin/www` Datei funktioniert und warum die `app.js` Datei +nicht mehr alleine startet. diff --git a/src/content/pages/de/guide/migrating-5.mdx b/src/content/pages/de/guide/migrating-5.mdx new file mode 100644 index 0000000000..7e243d0d03 --- /dev/null +++ b/src/content/pages/de/guide/migrating-5.mdx @@ -0,0 +1,678 @@ +--- +title: Umzug nach Express 5 +description: Eine umfassende Anleitung zur Migration Ihrer Express.js-Anwendungen von Version 4 auf 5, die aufwändige Änderungen, veraltete Methoden und neue Verbesserungen enthält. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express 5 unterscheidet sich nicht sehr von Express 4; obwohl es die gleiche grundlegende API hat, gibt es immer noch Änderungen, die die Kompatibilität mit der vorherigen Version stören. Daher könnte eine Anwendung mit Express 4 nicht funktionieren, wenn Sie sie auf Express 5 aktualisieren. + +Um diese Version zu installieren, benötigen Sie eine Node.js Version 18 oder höher. Führen Sie dann den folgenden Befehl in Ihrem Anwendungsverzeichnis aus: + +```sh +npm "express@5" installieren +``` + +Sie können dann Ihre automatisierten Tests durchführen, um zu sehen, was fehlschlägt, und Probleme gemäß den unten aufgeführten Updates beheben. Nach dem Beheben von Testfehlern führen Sie Ihre App aus, um zu sehen, welche Fehler auftreten. Sie werden sofort erfahren, ob die App Methoden oder Eigenschaften verwendet, die nicht unterstützt werden. + +## Express 5 Codemoden + +Um Ihnen zu helfen, Ihren Expressserver zu migrieren Wir haben eine Reihe von Codemods erstellt, die Ihnen helfen, Ihren Code automatisch auf die neueste Version von Express zu aktualisieren. + +Führen Sie den folgenden Befehl aus, um alle verfügbaren Codemods auszuführen: + +```sh +npx codemod@latest @expressjs/v5-migration-recipe +``` + +Wenn du eine bestimmte Codemod ausführen möchtest, kannst du folgenden Befehl ausführen: + +```sh +npx codemod@latest @expressjs/name-of-the-codemod +``` + +Du findest die Liste der verfügbaren Codemoden [here](https://codemod.link/express). + +## Änderungen in Express 5 + +**Entfernte Methoden und Eigenschaften** + + + +**Geändert** + + + +**Verbesserungen** + + + +## Entfernte Methoden und Eigenschaften + +Wenn du eine dieser Methoden oder Eigenschaften in deiner App verwendest, stürzt sie ab. Also müssen Sie Ihre App nach dem Update auf Version 5 ändern. + +### app.del() + +Express 5 unterstützt nicht mehr die `app.del()` Funktion. Wenn Sie diese Funktion verwenden, wird ein Fehler geworfen. Um HTTP DELETE Routen zu registrieren, benutze stattdessen die `app.delete()` Funktion. + +Anfangs wurde `del` anstelle von `delete` verwendet, da `delete` ein reserviertes Schlüsselwort in JavaScript ist. Jedoch können ECMAScript 6, `delete` und andere reservierte Schlüsselwörter legal als Eigenschaftsnamen verwendet werden. + + +Sie können die veralteten Signaturen durch folgenden Befehl ersetzen: + +```plaintext +npx codemod@latest @express js/route-del-to-delete +``` + + + +```js +// v4 +app.del('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); + +// v5 +app. elete('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); +``` + +### app.param(fn) + +Die Signatur `app.param(fn)` wurde verwendet, um das Verhalten der `app.param(name, fn)` Funktion zu ändern. Es ist seit v4.11.0 veraltet und Express 5 unterstützt es überhaupt nicht mehr. + +### Pluralisierte Methodennamen + +Die folgenden Methodennamen wurden pluralisiert. In Express 4 führte die Verwendung der alten Methoden zu einer Deprecation Warnung. Express 5 unterstützt sie nicht mehr: + +`req.acceptsCharset()` wird durch `req.acceptsCharsets()` ersetzt. + +`req.acceptsEncoding()` wird durch `req.acceptsEncodings()` ersetzt. + +`req.acceptsLanguage()` wird durch `req.acceptsLanguages()` ersetzt. + + +Sie können die veralteten Signaturen durch folgenden Befehl ersetzen: + +```plaintext +npx codemod@latest @expressjs/pluralize-method-names +``` + + + +```js +// v4 +app.all('/', (req, res) => { + req.acceptsCharset('utf-8'); + req. cceptsEncoding('br'); + req.acceptsLanguage('de'); + + // ... +}); + +// v5 +app. ll('/', (req, res) => { + req.acceptsCharsets('utf-8'); + req.acceptsEncodings('br'); + req.acceptsLanguages('de'); + + // ... +}); +``` + +### Führender Doppelpunkt (:) im Namen von app.param(name, fn) + +Ein führendes Doppelzeichen (:) im Namen der `app. aram(name, fn)` Funktion ist ein Überbleibsel von Express 3, und um der Abwärtskompatibilität willen hat Express 4 sie mit einer Veraltungsmeldung unterstützt. Express 5 ignoriert es stillschweigend und verwendet den Namensparameter, ohne ihn mit einem Doppelpunkt zu präfixieren. + +Dies sollte deinen Code nicht beeinflussen, wenn du der Express-4-Dokumentation von [app.param]folgst (/en/4x/api#app.param), da es keine Erwähnung des führenden Doppelpunkts. + +### req.param(Name) + +Diese potenziell verwirrende und gefährliche Methode zum Abrufen von Formulardaten wurde entfernt. Sie müssen nun gezielt nach dem übermittelten Parameternamen im `req.params`, `req.body` oder `req.query` Objekt suchen. + + +Sie können die veralteten Signaturen durch folgenden Befehl ersetzen: + +```plaintext +npx codemod@latest @expressjs/explicit-request-params +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + const id = req.param('id'); + const body = req. aram('body'); + const query = req.param('query'); + + // ... +}); + +// v5 +app.post('/user', (req, res) => { + const id = req.params. d; + const body = req.body; + const query = req.query; + + // ... +}); +``` + +### res.json(obj, Status) + +Express 5 unterstützt nicht mehr die Signatur `res.json(obj, status)`. Setze stattdessen den Status und verkette ihn auf die Methode `res.json()` wie folgt: `res.status(status).json(obj)`. + + +Sie können die veralteten Signaturen durch folgenden Befehl ersetzen: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.json({ name: 'Ruben' }, 201); +}); + +// v5 +app. ost('/user', (req, res) => { + res.status(201).json({ name: 'Ruben' }); +}); +``` + +### res.jsonp(obj, status) + +Express 5 unterstützt nicht mehr die Signatur `res.jsonp(obj, status)`. Setze stattdessen den Status und verkette ihn auf die `res.jsonp()` Methode wie folgt: `res.status(status).jsonp(obj)`. + + +Sie können die veralteten Signaturen durch folgenden Befehl ersetzen: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.jsonp({ name: 'Ruben' }, 201); +}); + +// v5 +app. ost('/user', (req, res) => { + res.status(201).jsonp({ name: 'Ruben' }); +}); +``` + +### res.redirect(url, Status) + +Express 5 unterstützt nicht mehr die Signatur `res.redirect(url, status)`. Verwenden Sie stattdessen die folgende Signatur: `res.redirect(status, url)`. + + +Sie können die veralteten Signaturen durch folgenden Befehl ersetzen: + +```plaintext +npx codemod@latest @expressjs/redirect-arg-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('/users', 301); +}); + +// v5 +app. et('/user', (req, res) => { + res.redirect(301, '/users'); +}); +``` + +### res.redirect('back') und res.location('back') + +Express 5 unterstützt nicht mehr den magischen String `back` in den Methoden `res.redirect()` und `res.location()`. Verwenden Sie stattdessen den `req.get('Referrer') || '/'` Wert, um zurück zur vorherigen Seite zu leiten. In Express 4 wurden die Methoden `res.redirect('back')` und `res.location('back')` veraltet. + + +Sie können die veralteten Signaturen durch folgenden Befehl ersetzen: + +```plaintext +npx codemod@latest @expressjs/back-redirect-deprecated +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('back'); +}); + +// v5 +app. et('/user', (req, res) => { + res.redirect(req.get('Referrer') || '/'); +}); +``` + +### res.send(Körper, Status) + +Express 5 unterstützt nicht mehr die Signatur `res.send(obj, status)`. Setze stattdessen den Status und verkette ihn auf die Methode `res.send()` wie folgt: `res.status(status).send(obj)`. + + +Sie können die veralteten Signaturen durch folgenden Befehl ersetzen: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send({ name: 'Ruben' }, 200); +}); + +// v5 +app. et('/user', (req, res) => { + res.status(200).send({ name: 'Ruben' }); +}); +``` + +### res.send(Status) + +Express 5 unterstützt nicht mehr die Signatur `res.send(status)`, wobei `status` eine Zahl ist. Verwenden Sie stattdessen die `res. endStatus(statusCode)` Funktion, die den HTTP-Antwort-Header-Statuscode setzt und die Textversion des Codes sendet: "Nicht gefunden", "Interner Server-Fehler", und so weiter. +Wenn Sie eine Nummer mit Hilfe der `res senden müssen. end()` Funktion, zitiert die Zahl, um sie in einen String zu konvertieren, so dass Express es nicht als Versuch interpretiert, die nicht unterstützte alte Signatur zu verwenden. + + +Sie können die veralteten Signaturen durch folgenden Befehl ersetzen: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send(200); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendStatus(200); +}); +``` + +### res.sendfile() + +Die `res.sendfile()` Funktion wurde durch eine camel-cased Version `res.sendFile()` in Express 5 ersetzt. + +**Hinweis:** In Express 5, `res. endFile()` verwendet das Paket `mime-types` für MIME Typenerkennung, welches verschiedene Content-Type Werte als Express 4 für mehrere gängige Dateitypen zurückgibt: + +* JavaScript-Dateien (.js): Jetzt "text/javascript" statt "application/javascript" +* JSON-Dateien (.json): jetzt "application/json" statt "text/json" +* CSS-Dateien (.css): Jetzt "text/css" statt "text/plain" +* XML-Dateien (.xml): jetzt "application/xml" statt "text/xml" +* Schriftdateien (.woff): Jetzt "font/woff" statt "application/font-woff" +* SVG-Dateien (.svg): jetzt "image/svg+xml" statt "application/svg+xml" + + +Sie können die veralteten Signaturen durch folgenden Befehl ersetzen: + +```plaintext +npx codemod@latest @expressjs/camelcase-sendfile +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.sendfile('/path/to/file'); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendFile('/path/to/file'); +}); +``` + +### router.param(fn) + +Die Signatur `router.param(fn)` wurde verwendet, um das Verhalten der `router.param(name, fn)` Funktion zu ändern. Es ist seit v4.11.0 veraltet und Express 5 unterstützt es überhaupt nicht mehr. + +### express.static.mime + +In Express 5 ist `mime` nicht mehr eine exportierte Eigenschaft des `static` Feldes. +Benutze das [`mime-types` package](https://github.com/jshttp/mime-types), um mit MIME Werte zu arbeiten. + +**Wichtig:** Diese Änderung beeinflusst nicht nur die direkte Verwendung von `express.static.mime`, sondern auch andere Express-Methoden, die auf die Erkennung des MIME-Typs angewiesen sind, wie `res.sendFile()`. Die folgenden MIME-Typen haben sich von Express 4 geändert: + +* JavaScript-Dateien (.js): Jetzt als "text/javascript" anstelle von "application/javascript" +* JSON-Dateien (.json): Jetzt als "application/json" anstelle von "text/json" +* CSS-Dateien (.css): Jetzt als "text/css" anstelle von "text/plain" +* HTML-Dateien (): Wird nun als "text/html; charset=utf-8" anstelle von "text/html" ausgegeben. +* XML-Dateien (.xml): Jetzt als "application/xml" anstelle von "text/xml" +* Schriftdateien (.woff): Jetzt als "font/woff" anstelle von "application/font-woff" + +```js +// v4 +express.static.mime.lookup('json'); + +// v5 +const mime = require('mime-types'); +mime.lookup('json'); +``` + +### express:router Debug-Logs + +In Express 5 wird die Router-Handhabungslogik durch eine Abhängigkeit ausgeführt. Daher sind die +Debug-Logs für den Router nicht mehr unter dem `express :` Namensraum verfügbar. +In v4 waren die Protokolle unter den Namensräumen `express:router`, `express:router:layer`, +und `express:router:route` verfügbar. Alle diese wurden unter den Namensraum `express:*` aufgenommen. +In v5.1+ sind die Logs unter den Namensräumen `router`, `router:layer` und `router:route` verfügbar. +Die Logs von `router:layer` und `router:route` sind im Namensraum `router:*` enthalten. +Um das selbe Detail der Debug-Protokollierung mit `express:*` in v4 zu erreichen, benutze eine Verbindung von +`express:*`, `router` und `router:*`. + +```sh + +DEBUG=Express:* node index.js + + +DEBUG=Express:*,router,router:* node index.js +``` + +## Geändert + +### Pfad Route übereinstimmende Syntax + +Syntax für Pfadrouten ist, wenn als erster Parameter `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()` und `router.use()` APIs angegeben wird. Die folgenden Änderungen wurden vorgenommen, wie der Pfad-String auf eine eingehende Anfrage abgestimmt wird: + +* Das Platzhalter `*` muss einen Namen haben, passend zum Verhalten der Parameter `:`, verwende `/*splat` statt `/*` + +```js +// v4 +app.get('/*', async (req, res) => { + res.send('ok'); +}); + +// v5 +app. et('/*splat', async (req, res) => { + res.send('ok'); +}); +``` + + +`*splat` entspricht jedem Pfad ohne den Wurzelpfad. Wenn du den Wurzelpfad auch `/` anpassen musst, kannst du `/{*splat}` verwenden, indem du den Platzhalter in Klammern verpackst. + +```js +// v5 +app.get('/{*splat}', async (req, res) => { + res.send('ok'); +}); +``` + + + +* Das optionale Zeichen `?` wird nicht mehr unterstützt, verwende stattdessen Klammern. + +```js +// v4 +app.get('/:file.:ext?', async (req, res) => { + res.send('ok'); +}); + +// v5 +app. et('/:file{.:ext}', async (req, res) => { + res.send('ok'); +}); +``` + +* Regexp Zeichen werden nicht unterstützt. Zum Beispiel: + +```js +app.get('/[discussion|page]/:slug', async (req, res) => { + res.status(200).send('ok'); +}); +``` + +sollte geändert werden: + +```js +app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { + res.status(200).send('ok'); +}); +``` + +* Einige Zeichen wurden reserviert, um Verwirrung während des Upgrades zu vermeiden (`()[]?+!`), verwenden Sie `\` um sie zu maskieren. +* Parameternamen unterstützen nun gültige JavaScript-Identifikatoren oder zitiert wie `:"this`. + +### Abgelehnte Versprechen von Middleware und Handlern + +Fordern Sie Middleware und Handler an, die abgelehnte Versprechungen zurückgeben, werden nun durch die Weiterleitung des zurückgewiesenen Wertes als `Error` an die Fehlerbehandlung Middleware behandelt. Das bedeutet, dass die Verwendung von `async` Funktionen als Middleware und Handler einfacher ist als je zuvor. Wenn ein Fehler in einer `async`-Funktion oder einem abgewiesenen Versprechen geworfen wird, wird `erwartet in einer async-Funktion, diese Fehler werden an den Fehlerhandler übergeben, als ob `next(err)\` aufgerufen würde. + +Details darüber, wie Express mit Fehlern umgeht, finden Sie in der [Dokumentation zur Fehlerbehandlung](/en/guide/error-handling). + +### express.urlencoded + +Die `express.urlencoded` Methode erzeugt standardmäßig die `extended` Option `false`. + +### express.static dotfiles + +In Express 5 ist die Option `express.static` middleware `dotfiles` nun standardmäßig `"ignore`. Dies ist eine Änderung von Express 4, wo dotfiles standardmäßig bedient wurden. Als Ergebnis sind Dateien in einem Verzeichnis, das mit einem Punkt (`.`) beginnt, wie `. ell-known`, wird nicht mehr erreichbar sein und einen **404 Nicht gefunden** Fehler zurückgeben. Dies kann die Funktionalität, die von der Bereitstellung von Dot-Verzeichnissen abhängt, wie Android App Links und Apple Universal Links, beschädigen. + +Beispiel für Break-Code: + +```js +// v4 +app.use(express.static('public')); +``` + +Nach der Migration auf Express 5 wird eine Anfrage an `/.well-known/assetlinks.json` zu einem **404 Nicht Found** führen. + +Um dies zu beheben, geben Sie bestimmte dot-Verzeichnisse explizit mit der `dotfiles: "allow"` Option aus: + +```js +// v5 +app.use('/.well-known', express.static('public/.well-known', { dotfiles: 'allow' })); +app.use(express.static('public')); +``` + +Mit diesem Ansatz können Sie sicher nur die beabsichtigten dot-Verzeichnisse bedienen und gleichzeitig das standardmäßige sichere Verhalten für andere dotfiles beibehalten, die nicht zugänglich sind. + +### app.hören + +In Express 5 ruft die `app.listen` Methode die vom Benutzer zur Verfügung gestellte Callback-Funktion auf, wenn der Server ein Fehlerereignis erhält. In Express 4 würden solche Fehler aufgeworfen. Diese Änderung verlagert die Verantwortung für die Fehlerbehandlung auf die Callback-Funktion in Express 5. Wenn ein Fehler auftritt, wird er als Argument an den Callback übergeben. +Zum Beispiel: + +```js +const server = app.listen(8080, '0.0.0.0', (error) => { + if (error) { + throw error; // e.g. EADDRINUSE + } + console.log(`Listening auf ${JSON.stringify(server.address())}`); +}); +``` + +### app.router + +Das `app.router` Objekt, das in Express 4 entfernt wurde, hat ein Comeback in Express 5 gemacht. In der neuen Version ist dieses Objekt nur eine Referenz auf den Basis-Express-Router, im Gegensatz zu Express 3, wo eine App sie explizit laden musste. + +### req.body + +Die Eigenschaft `req.body` gibt `undefined` zurück, wenn der Body nicht analysiert wurde. In Express 4 gibt es standardmäßig `{}` zurück. + +### req.host + +In Express 4 hat die `req.host` Funktion die Portnummer falsch entfernt, wenn sie vorhanden war. In Express 5 wird die Portnummer beibehalten. + +### req.params + +Das `req.params` Objekt hat nun einen **null Prototyp** wenn man String Pfade benutzt. Wenn der Pfad jedoch mit einem regulären Ausdruck definiert ist, bleibt `req.params` ein Standardobjekt mit einem normalen Prototyp. Zusätzlich gibt es zwei wichtige Verhaltensänderungen: + +**Wildcard-Parameter sind jetzt Arrays:** + +Platzhalter (z.B. `/*splat`) erfassen Pfadsegmente als Array anstelle eines einzelnen Strings. + +```js +app.get('/*splat', (req, res) => { + // GET /foo/bar + console.dir(req. arams); + // => [Objekt: null prototype] { splat: [ 'foo', 'bar' ] } +}); +``` + +**Unübereinstimmende Parameter werden weggelassen:** + +In Express 4 waren unpassende Platzhalter leere Zeichenketten (`''`) und optionale `:` Parameter (mit `?`) hatten einen Schlüssel mit dem Wert `undefiniert`. In Express 5 werden unübertroffene Parameter vollständig aus `req.params` entfernt. + +```js +// v4: unerreichter Platzhalter ist leerer String +app.get('/*', (req, res) => { + // GET / + console.dir(req. arams); + // => { '0': '' } +}); + +// v4: unübertroffener optionaler Parameter ist nicht definiert +app. et('/:file.:ext?', (req, res) => { + // GET /image + Konsole. ir(req.params); + // => { file: 'image', ext: undefined } +}); + +// v5: unmatched optional param is omitted +app.get('/:file{. ext}', (req, res) => { + // GET /image + console.dir(req. arams); + // => [Objekt: null prototype] { Datei: 'image' } +}); +``` + +### req.query + +Die Eigenschaft `req.query` ist keine beschreibbare Eigenschaft mehr und ist stattdessen ein Getter. Der Standard-Query-Parser wurde von "extended" auf "simple" geändert. + +### res.clearCookie + +Die Methode `res.clearCookie` ignoriert die vom Benutzer bereitgestellten `maxAge` und `expires` Optionen. + +### res.status + +Die `res.status` Methode akzeptiert nur ganze Zahlen im Bereich `100` bis `999`, gefolgt von dem von Knoten definierten Verhalten. , und gibt einen Fehler zurück, wenn der Statuscode keine Ganzzahl ist. + +### res.variieren + +Das `res.vary` wirft einen Fehler auf, wenn das `field` Argument fehlt. In Express 4, wenn das Argument weggelassen wurde, gab es eine Warnung in der Konsole + +## Verbesserungen + +### res.render() + +Diese Methode erzwingt jetzt asynchrones Verhalten für alle View Engines, Fehler zu vermeiden, die von View Engines verursacht wurden, die eine synchrone Implementierung hatten und die gegen die empfohlene Schnittstelle verstoßen. + +### Unterstützung für Brotli Kodierung + +Express 5 unterstützt die Kodierung von Brotli für Anfragen von Kunden, die es unterstützen. diff --git a/src/content/pages/de/resources/glossary.mdx b/src/content/pages/de/resources/glossary.mdx new file mode 100644 index 0000000000..6925e982ee --- /dev/null +++ b/src/content/pages/de/resources/glossary.mdx @@ -0,0 +1,61 @@ +--- +title: Glossary +description: Ein umfassendes Glossar mit Begriffen, die sich auf Express.js, Node.js, Middleware, Routing und andere Schlüsselkonzepte beziehen, damit Sie Express verstehen und effektiv nutzen können. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +### anwendung + +Im Allgemeinen ein oder mehrere Programme, die darauf ausgelegt sind, Operationen für einen bestimmten Zweck durchzuführen. Im Kontext von Express, ein Programm, das die Express-API verwendet, die auf der Node.js-Plattform läuft. Könnte auch auf ein [app object](/en/api#express). + +### API + +Programmierschnittstelle für Anwendungen. Sprich die Abkürzung aus, wenn sie zum ersten Mal verwendet wird. + +### Express + +Ein schnelles, unübersichtliches, minimalistisches Webframework für Node.js Anwendungen. Im Allgemeinen wird "Express" von "Express.js" bevorzugt, obwohl letztere akzeptabel ist. + +### libuv + +Eine mehrplattformunabhängige Unterstützungsbibliothek, die sich auf asynchrone I/O konzentriert, die hauptsächlich für den Einsatz durch Node.js entwickelt wurde. + +### Middleware + +Eine Funktion, die von der Express-Routing Layer vor dem letzten Request-Handler aufgerufen wird und sitzt somit in der Mitte zwischen einer Rohanforderung und der endgültigen geplanten Route. Ein paar schöne Terminologiepunkte rund um die Middleware: + +* `var foo = require('middleware')` heißt *requiring* oder *using* ein Node.js Modul. Dann gibt die Anweisung `var mw = foo()` typischerweise die Middleware zurück. +* `app.use(mw)` heißt *adding the middleware to the global processing stack*. +* `app.get('/foo', mw, function (req, res) { ... })` heißt *adding the middleware to the "GET /foo" processing stack*. + +### Node.js + +Eine Softwareplattform, die zur Erstellung skalierbarer Netzwerkanwendungen verwendet wird. Node.js verwendet JavaScript als Skriptsprache und erzielt einen hohen Durchsatz über nicht-blockierende I/O und eine einzige Threading-Ereignisschleife. Siehe [nodejs.org](https://nodejs.org/en/). **Verwende Notiz**: Anfangs "Node.js", danach "Knoten". + +### Open-Source, Open-Source + +Wenn als Adjektiv verwendet wird, Bindestrich; zum Beispiel: "Dies ist Open-Source-Software." Siehe [Open-Source-Software auf Wikipedia](http://en.wikipedia.org/wiki/Open-source_software). + + + +Obwohl es üblich ist, diesen Begriff nicht zu überschreiben, verwenden wir die üblichen englischen Regeln für +und hyphenieren ein Compound Adjektiv. + + + +### anfragen + +Eine HTTP-Anfrage. Ein Client sendet eine HTTP-Anfrage an einen Server, der eine Antwort zurückgibt. Die Anfrage muss eine von mehreren [Anfragemethoden](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) wie GET, POST usw. verwenden. + +### antwort + +Eine HTTP-Antwort. Ein Server gibt dem Client eine HTTP-Antwortmeldung zurück. Die Antwort enthält Vollständigkeitsinformationen über die Anfrage und kann auch angeforderte Inhalte in ihrem Nachrichtentext enthalten. + +### routen + +Teil einer URL, die eine Ressource identifiziert. In `http://foo.com/products/id`, zum Beispiel, ist "/products/id" die Route. + +### router + +Siehe [router](/en/api#router) in der API-Referenz. diff --git a/src/content/pages/de/resources/utils.md b/src/content/pages/de/resources/utils.md new file mode 100644 index 0000000000..ddac36359a --- /dev/null +++ b/src/content/pages/de/resources/utils.md @@ -0,0 +1,22 @@ +--- +title: Expresswerkzeuge +description: Entdecken Sie die Utility-Module von Express.js und Node.js, einschließlich Tools für Cookies, CSRF-Schutz, URL-Parsing, Routing und vieles mehr, um Ihre Anwendungen zu verbessern. +--- + +## Express Utility-Funktionen + +Die [pillarjs](https://github.com/pillarjs) GitHub Organisation enthält eine Reihe von Modulen +für Utility-Funktionen, die allgemein nützlich sein können. + +| Utility Module | Beschreibung | +| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [cookies](https://www.npmjs.com/package/cookies) | Erhalten und setzen Sie HTTP(S)-Cookies, die signiert werden können, um Manipulationen mit Hilfe von Keygrip zu verhindern. Kann mit der Node.js HTTP-Bibliothek oder als Express Middleware verwendet werden. | +| [csrf](https://www.npmjs.com/package/csrf) | Enthält die Logik hinter der Erstellung und Verifizierung von CSRF-Token. Verwenden Sie dieses Modul, um benutzerdefinierte CSRF Middleware zu erstellen. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Funktion, die als letzter Schritt aufgerufen wird, um auf HTTP-Anfrage zu reagieren. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Eine URL mit Cache analysieren. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Verwandeln Sie einen Express-Style Pfadstring wie \`\`/user/:name\` in einen regulären Ausdruck. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Behebt einen relativen Pfad gegen einen Wurzelpfad mit Validierung. | +| [router](https://www.npmjs.com/package/router) | Einfacher Middleware-Router. | +| [send](https://www.npmjs.com/package/send) | Bibliothek zum Streamen von Dateien als HTTP-Antwort, mit Unterstützung für partielle Antworten (Bereiche), Konditional-GET-Verhandlung und granulare Ereignisse. | + +Weitere HTTP-basierte Module finden Sie unter [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/de/support.md b/src/content/pages/de/support.md new file mode 100644 index 0000000000..c93cb5a15d --- /dev/null +++ b/src/content/pages/de/support.md @@ -0,0 +1,23 @@ +--- +title: Versionsunterstützung +description: Finden Sie Informationen über den Support-Zeitplan für verschiedene Express.js Versionen, einschließlich der aktuellen Versionen und der End-of-Life-Richtlinien. +--- + +Nur die neueste Version einer der wichtigsten Release-Zeilen wird unterstützt. + +Versionen, die EOL (Ende des Lebens) _may_ sind, erhalten Updates für kritische Sicherheitslücken, aber das Express-Team bietet keine Garantie und plant keine Korrekturen für festgestellte Probleme zu beheben oder zu veröffentlichen. + +| Hauptversion | Minimale Node.js Version | Support-Startdatum | Support-Enddatum | +| ------------------------------------------- | ---------------------------------------- | ------------------ | ---------------- | +| [**v5.x**](/en/5x/api) | 18 | September 2024 | **Laufend** | +| [**v4.x**](/en/4x/api) | 0.10.0 | April 2014 | **Laufend** | +| [**v3.x**](/en/3x/api) | 0.8.0 | Oktober 2012 | Juli 2015 | +| [**v2.x**](/2x/) | 0.4.1 | März 2011 | Juli 2012 | +| **v1.x** | 0.2.0 | Dezember 2010 | März 2011 | +| **v0.14.x** | 0.1.98 | Dezember 2010 | Dezember 2010 | + +## Kommerzielle Support-Optionen + +Wenn Sie nicht in der Lage sind, auf eine unterstützte Version von Express zu aktualisieren, wenden Sie sich bitte an einen unserer Partner, um Sicherheitsaktualisierungen zu erhalten: + +- [HeroDevs unendlicher Support](http://www.herodevs.com/support/express-nes?utm_source=expressjs&utm_medium=link&utm_campaign=express_eol_page) diff --git a/src/content/pages/es/advanced/best-practice-performance.md b/src/content/pages/es/advanced/best-practice-performance.md new file mode 100644 index 0000000000..575a6a97d8 --- /dev/null +++ b/src/content/pages/es/advanced/best-practice-performance.md @@ -0,0 +1,305 @@ +--- +title: 'Mejores prácticas de producción: rendimiento y fiabilidad' +description: Descubra las mejores prácticas de rendimiento y fiabilidad para aplicaciones Express en producción, cubriendo optimizaciones de código y configuraciones de entorno para un rendimiento óptimo. +--- + +Este artículo analiza el rendimiento y la fiabilidad de las mejores prácticas para aplicaciones Express implementadas en producción. + +Este tema entra claramente en el mundo de los "devops", que abarca tanto el desarrollo tradicional como las operaciones. En consecuencia, la información se divide en dos partes: + +- Cosas que hacer en tu código (la parte del desarrollador): + - [Usar compresión gzip](#use-gzip-compression) + - [No usar funciones sincrónicas](#dont-use-synchronous-functions) + - [Registrar correctamente] (#do-logging-correctly) + - [Manejar excepciones correctamente](#handle-exceptions-properly) +- Cosas que hacer en tu entorno / configuración (parte de la opción): + - [Establecer NODE_ENV a "producción"](#set-node_env-to-production) + - [Asegúrate de que tu aplicación se reinicie automáticamente](#ensure-your-app-automatically-restarts) + - [Ejecutar tu aplicación en un clúster](#run-your-app-in-a-cluster) + - [Cache request results](#cache-request-results) + - [Usa un balanceador de carga](#use-a-load-balancer) + - [Usa un proxy inverso](#use-a-reverse-proxy) + +## Cosas que hacer en tu código + +Aquí hay algunas cosas que puedes hacer en tu código para mejorar el rendimiento de tu aplicación: + +- [Usar compresión gzip](#use-gzip-compression) +- [No usar funciones sincrónicas](#dont-use-synchronous-functions) +- [Registrar correctamente] (#do-logging-correctly) +- [Manejar excepciones correctamente](#handle-exceptions-properly) + +### Usar compresión gzip + +La compresión Gzip puede disminuir en gran medida el tamaño del cuerpo de respuesta y por lo tanto aumentar la velocidad de una aplicación web. Utilice el Middleware [compression](https://www.npmjs.com/package/compression) para compresión gzip en su aplicación Express. Por ejemplo: + +```js +const compression = require('compression'); +const express = require('express'); +const app = express(); + +app.use(compression()); +``` + +Para un sitio web de alto tráfico en producción, la mejor manera de poner compresión en su lugar es implementarla en un nivel proxy inverso (ver [Usar un proxy inverso](#use-a-reverse-proxy)). En ese caso, no necesita usar middleware de compresión. Para más detalles sobre habilitar compresión gzip en Nginx, vea [Módulo ngx_http_gzip_module](http://nginx.org/en/docs/http/ngx_http_gzip_module) en la documentación de Nginx. + +### No utilizar funciones sincrónicas + +Las funciones y métodos sincrónicos emiten el proceso de ejecución hasta que regresen. Una sola llamada a una función sincrónica puede regresar en unos pocos microsegundos o milisegundos, Sin embargo, en sitios web de alto tráfico, estas llamadas añaden y reducen el rendimiento de la aplicación. Evite su uso en la producción. + +Aunque Node y muchos módulos proporcionan versiones sincrónicas y asíncronas de sus funciones, siempre utiliza la versión asíncrona en producción. La única vez que una función sincrónica puede ser justificada es al inicio inicial. + +Puedes usar la bandera de línea de comandos `--trace-sync-io` para imprimir una advertencia y un stack trace cada vez que tu aplicación usa una API sincrónica. Por supuesto, no querrías usar esto en la producción, sino más bien asegurar que tu código esté listo para la producción. Vea la [documentación de opciones de línea de comandos de nodo](https://nodejs.org/api/cli#cli_trace_sync_io) para más información. + +### Hacer el registro correctamente + +En general, hay dos razones para registrarse desde tu aplicación: para depurar y para registrar la actividad de la aplicación (esencialmente, todo lo demás). Usar `console.log()` o `console.error()` para imprimir mensajes de registro en la terminal es práctica común en desarrollo. Pero [estas funciones son sincrónicas](https://nodejs.org/api/console#console) cuando el destino es un terminal o un archivo, por lo que no son aptos para la producción, a menos que usted pipe la salida a otro programa. + +#### Para depuración + +Si está registrando para fines de depuración, entonces en lugar de usar `console.log()`, utilice un módulo especial de depuración como [debug](https://www.npmjs.com/package/debug). Este módulo le permite usar la variable de entorno DEBUG para controlar qué mensajes de depuración se envían a `console.error()`, si los hay. Para mantener tu aplicación puramente asincrónica, todavía quieres pipe `console.error()` a otro programa. Pero entonces, no vas a depurar en la producción, ¿verdad? + +#### Para actividad de la aplicación + +Si estás registrando actividad de la aplicación (por ejemplo, rastreando tráfico o llamadas de API), en lugar de usar `console. og()`, utiliza una biblioteca de registro como [Pino](https://www.npmjs.com/package/pino), que es la opción más rápida y eficiente disponible. + +### Manejar excepciones correctamente + +Las aplicaciones del nodo fallan cuando se encuentran con una excepción no capturada. No manejar excepciones y tomar las acciones apropiadas hará que su aplicación Express se bloquee y se desconecte. Si sigues los consejos de [Asegúrate de que tu aplicación se reinicie automáticamente](#ensure-your-app-automatically-restarts) a continuación, tu aplicación se recuperará de un cuelgue. Afortunadamente, las aplicaciones Express típicamente tienen un corto tiempo de inicio. Sin embargo, usted quiere evitar el bloqueo en primer lugar, y para hacerlo, necesita manejar las excepciones adecuadamente. + +Para asegurar que maneja todas las excepciones, utilice las siguientes técnicas: + +- [Usar try-catch](#use-try-catch) +- [Usar promesas](#use-promises) + +Antes de sumergirte en estos temas, deberías tener una comprensión básica del manejo de errores de Node/Express: usando callbacks de primer error, y propagando errores en middleware. Node utiliza una convención de "error de primer callback" para devolver errores de funciones asíncronas, donde el primer parámetro de la función callback es el objeto de error, seguido de los datos de resultado en los parámetros posteriores. Para indicar ningún error, pase nulo como el primer parámetro. La función callback debe seguir la convención de devolución de llamada de primer error para manejar el error de forma significativa. Y en Express, la mejor práctica es usar la función next() para propagar errores a través de la cadena middleware. + +Para más información sobre los fundamentos del manejo de errores, vea: + +- [Manejo de Error en Node.js](https://www.tritondatacenter.com/node-js/production/design/errors) + +#### Usar try-catch + +Try-catch es una construcción de lenguaje JavaScript que se puede utilizar para capturar excepciones en código sincrónico. Use try-catch, por ejemplo, para manejar errores de análisis JSON como se muestra a continuación. + +He aquí un ejemplo del uso de try-catch para manejar una posible excepción de bloqueo de procesos. +Esta función middleware acepta un parámetro de campo de consulta llamado "params" que es un objeto JSON. + +```js +app.get('/search', (req, res) => { + // Simulating async operation + setImmediate(() => { + const jsonStr = req.query.params; + try { + const jsonObj = JSON.parse(jsonStr); + res.send('Success'); + } catch (e) { + res.status(400).send('Invalid JSON string'); + } + }); +}); +``` + +Sin embargo, try-catch funciona sólo para código sincrónico. Debido a que la plataforma de Node es principalmente asíncrona (especialmente en un entorno de producción), la captura de pruebas no capturará muchas excepciones. + +#### Utilizar promesas + +Cuando se arroja un error en una función `async` o se espera una promesa rechazada dentro de una función `async`, esos errores se pasarán al gestor de errores como si llamara a `next(err)` + +```js +app.get('/', async (req, res, next) => { + const data = await userData(); // If this promise fails, it will automatically call `next(err)` to handle the error. + + res.send(data); +}); + +app.use((err, req, res, next) => { + res.status(err.status ?? 500).send({ error: err.message }); +}); +``` + +También, puede utilizar funciones asíncronas para su middleware, y el router manejará errores si la promesa falla, por ejemplo: + +```js +app.use(async (req, res, next) => { + req.locals.user = await getUser(req); + + next(); // This will be called if the promise does not throw an error. +}); +``` + +La mejor práctica es manejar los errores lo más cerca posible del sitio. Así que mientras esto se maneja ahora en el router, es mejor capturar el error en el middleware y manejarlo sin depender de middleware separado para manejar errores. + +#### Qué no hacer + +Una cosa que debes _no_ hacer es escuchar el evento `uncaughtException`, emitido cuando una excepción emite todo el camino de regreso al bucle del evento. Añadir un detector de eventos para `uncaughtException` cambiará el comportamiento predeterminado del proceso que se encuentra con una excepción; el proceso continuará funcionando a pesar de la excepción. Esto puede sonar como una buena manera de evitar que tu aplicación falle, pero seguir ejecutando la aplicación después de una excepción no capturada es una práctica peligrosa y no se recomienda, porque el estado del proceso se vuelve poco fiable e impredecible. + +Además, usar `uncaughtException` es oficialmente reconocido como [crude](https://nodejs.org/api/process#process_event_uncaughtexception). Así que escuchar `uncaughtException` es sólo una mala idea. Por eso recomendamos cosas como múltiples procesos y supervisores: fallar y reiniciar es a menudo la manera más confiable de recuperarse de un error. + +Tampoco recomendamos usar [domains](https://nodejs.org/api/domain). Generalmente no resuelve el problema y es un módulo obsoleto. + +## Cosas que hacer en tu entorno / configuración + +Aquí hay algunas cosas que puedes hacer en el entorno de tu sistema para mejorar el rendimiento de tu aplicación: + +- [Establecer NODE_ENV a "producción"](#set-node_env-to-production) +- [Asegúrate de que tu aplicación se reinicie automáticamente](#ensure-your-app-automatically-restarts) +- [Ejecutar tu aplicación en un clúster](#run-your-app-in-a-cluster) +- [Cache request results](#cache-request-results) +- [Usa un balanceador de carga](#use-a-load-balancer) +- [Usa un proxy inverso](#use-a-reverse-proxy) + +### Establecer NODE_ENV a "producción" + +La variable de entorno NODE_ENV especifica el entorno en el que se está ejecutando una aplicación (normalmente, desarrollo o producción). Una de las cosas más sencillas que puedes hacer para mejorar el rendimiento es establecer NODE_ENV en `production`. + +Establecer NODE_ENV a "producción" hace Expresión: + +- Plantillas de vista de caché. +- Caché de archivos CSS generados a partir de extensiones CSS. +- Generar mensajes de error menos detallados. + +¡[Las pruebas indican](https://www.dynatrace.com/news/blog/the-drastic-effects-of-omitting-node-env-in-your-express-js-applications/) que hacer esto puede mejorar el rendimiento de la aplicación en un factor de tres! + +Si necesita escribir código específico del entorno, puede comprobar el valor de NODE_ENV con `process.env.NODE_ENV`. Tenga en cuenta que comprobar el valor de cualquier variable de entorno incurre en una penalidad de rendimiento, y por lo tanto debe hacerse de forma esparcida. + +En desarrollo, normalmente estableces variables de entorno en tu shell interactivo, por ejemplo usando `export` o tu archivo `.bash_profile`. Pero en general, no debería hacer esto en un servidor de producción; en cambio, utilice el sistema de inicio de su sistema operativo (systemd). La siguiente sección proporciona más detalles sobre el uso de tu sistema de inicio en general pero configurar `NODE_ENV` es tan importante para el rendimiento (y fácil de hacer), que está resaltado aquí. + +Con el sistema, utilice la directiva 'Entorno de Entorno' en su archivo de unidad. Por ejemplo: + +```sh + +Environment=NODE_ENV=production +``` + +Para obtener más información, consulte [Usar variables de entorno en unidades del sistema](https://www.flatcar.org/docs/latest/setup/systemd/environment-variables/). + +### Asegúrate de que tu aplicación se reinicie automáticamente + +En la producción, usted no quiere que su aplicación esté fuera de línea, nunca. Esto significa que necesita asegurarse de que se reinicie si la aplicación se bloquea y si el servidor mismo falla. Aunque usted espera que ninguno de estos eventos ocurra, realísticamente usted debe dar cuenta de ambos eventos por: + +- Usar un gestor de procesos para reiniciar la aplicación (y Node) cuando se bloquea. +- Usando el sistema de inicio proporcionado por su sistema operativo para reiniciar el gestor de procesos cuando el sistema operativo se bloquea. También es posible usar el sistema init sin un gestor de procesos. + +Las aplicaciones de nodos se estrellan si se encuentran con una excepción no capturada. Lo más importante que tienes que hacer es asegurar que tu aplicación está bien probada y gestiona todas las excepciones (ver [excepciones de manejo correctamente](#handle-exceptions-properly) para más detalles). Pero como seguro de fallos, ponga en marcha un mecanismo para asegurar que si tu aplicación se bloquea y cuando se bloquee, se reiniciará automáticamente. + +#### Usar un gestor de procesos + +En desarrollo, ha iniciado su aplicación simplemente desde la línea de comandos con `node server.js` o algo similar. Pero hacer esto en la producción es una receta para el desastre. Si la aplicación falla, estará desconectada hasta que la reinicie. Para asegurar que su aplicación se reinicie si se bloquea, utilice un gestor de procesos. Un gestor de procesos es un "contenedor" para aplicaciones que facilita el despliegue, proporciona alta disponibilidad y le permite gestionar la aplicación en tiempo de ejecución. + +Además de reiniciar su aplicación cuando falla, un gestor de procesos puede habilitarlo: + +- Obtener información sobre el rendimiento y el consumo de recursos en tiempo de ejecución. +- Modificar ajustes dinámicamente para mejorar el rendimiento. +- Clasificación de controles (pm2). + +Históricamente, era popular usar un gestor de procesos Node.js como [PM2](https://github.com/Unitech/pm2). Vea su documentación si desea hacer esto. Sin embargo, recomendamos usar su sistema de inicio para la gestión de procesos. + +#### Usar un sistema de inicio + +La siguiente capa de fiabilidad es asegurar que la aplicación se reinicie cuando el servidor se reinicie. Los sistemas pueden seguir bajando por diversas razones. Para asegurarse de que su aplicación se reinicie si el servidor se bloquea, utilice el sistema init incorporado en su sistema operativo. El sistema principal de inicio en uso hoy es [systemd](https://wiki.debian.org/systemd). + +Hay dos formas de usar sistemas de inicio con su aplicación Express: + +- Ejecute su aplicación en un gestor de procesos, e instale el gestor de procesos como un servicio con el sistema init. El gestor de procesos reiniciará la aplicación cuando la aplicación se bloquee, y el sistema de inicio reiniciará el gestor de procesos cuando el sistema operativo se reinicie. Este es el enfoque recomendado. +- Ejecute su aplicación (y Node) directamente con el sistema init. Esto es algo más simple, pero no obtiene las ventajas adicionales de usar un gestor de procesos. + +##### Systemd + +Systemd es un gestor de servicios y sistemas Linux. La mayoría de las distribuciones de Linux más importantes han adoptado el sistema de inicio como su sistema predeterminado. + +Un archivo de configuración de servicio systemd se llama _unit file_, con un nombre de archivo que termina en `.service`. Aquí hay un archivo de unidad de ejemplo para administrar directamente una aplicación de Node. Reemplaza los valores encerrados en `` para tu sistema y aplicación: + +```sh +[Unit] +Description= + +[Service] +Type=simple +ExecStart=/usr/local/bin/node +WorkingDirectory= + +User=nobody +Group=nogroup + + +Environment=NODE_ENV=production + + +LimitNOFILE=infinity + + +LimitCORE=infinity + +StandardInput=null +StandardOutput=syslog +StandardError=syslog +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +Para más información sobre el sistema, vea la [referencia del sistema (página de manu)] (http://www.freedesktop.org/software/systemd/man/systemd.unit). + +### Ejecutar tu aplicación en un clúster + +En un sistema multinúcleo, puede aumentar el rendimiento de una aplicación Node muchas veces lanzando un clúster de procesos. Un clúster ejecuta múltiples instancias de la aplicación, idealmente una instancia en cada núcleo de CPU, distribuyendo así la carga y las tareas entre las instancias. + +![Balanceo entre las instancias de la aplicación usando la API del clúster](/images/clustering.png) + +IMPORTANTE: Dado que las instancias de la aplicación se ejecutan como procesos separados, no comparten el mismo espacio de memoria. Es decir, los objetos son locales a cada instancia de la aplicación. Por lo tanto, no puede mantener el estado en el código de la aplicación. Sin embargo, puede utilizar un datastore en memoria como [Redis](http://redis.io/) para almacenar datos y estado relacionados con la sesión. Esta advertencia se aplica esencialmente a todas las formas de escalado horizontal, ya sea en racimo con múltiples procesos o múltiples servidores físicos. + +En las aplicaciones agrupadas, los procesos del worker pueden fallar individualmente sin afectar al resto de los procesos. Aparte de las ventajas de rendimiento, el aislamiento de fallos es otra razón para ejecutar un cluster de procesos de aplicaciones. Cada vez que un proceso worker se bloquea, siempre asegúrese de registrar el evento y generar un nuevo proceso usando cluster.fork(). + +#### Usando el módulo de cluster del nodo + +Clustering es posible con el [módulo de cluster]de Node (https://nodejs.org/api/cluster). Esto permite que un proceso maestro genere procesos de trabajador y distribuya conexiones entrantes entre los trabajadores. + +#### Usando PM2 + +Si implementa su aplicación con PM2, puede aprovechar el clustering _without_ modificando su código de aplicación. Deberías asegurarte de que tu [aplicación está sin estado](https://pm2.keymetrics.io/docs/usage/specifics/#stateless-apps) primero, lo que significa que no hay datos locales almacenados en el proceso (como sesiones, conexiones websocket y similares). + +Cuando ejecutas una aplicación con PM2, puedes habilitar el **modo clúster** para ejecutarla en un clúster con varias instancias de tu elección, como el número de CPUs disponibles en la máquina. Puede cambiar manualmente el número de procesos en el clúster usando la herramienta de línea de comandos `pm2` sin detener la aplicación. + +Para activar el modo cluster, inicia tu aplicación así: + +```bash + +$ pm2 start npm --name my-app -i 4 -- start + +$ pm2 start npm --name my-app -i max -- start +``` + +Esto también se puede configurar dentro de un archivo de proceso PM2 (`ecosystem.config. s` o similar) estableciendo `exec_mode` a `cluster` y `instancias` al número de workers a comenzar. + +Una vez ejecutada, la aplicación puede escalarse así: + +```bash + +$ pm2 scale my-app +3 + +$ pm2 scale my-app 2 +``` + +Para más información sobre el clustering con PM2, vea [Modo Cluster](https://pm2.keymetrics.io/docs/usage/cluster-mode/) en la documentación de PM2. + +### Resultados de la solicitud de caché + +Otra estrategia para mejorar el rendimiento en la producción es almacenar en caché el resultado de las solicitudes, para que tu aplicación no repita la operación para servir la misma petición repetidamente. + +Usa un servidor de caché como [Varnish](https://www.varnish-cache.org/) o [Nginx](https://blog.nginx.org/blog/nginx-caching-guide) (ver también [Caching Nginx](https://serversforhackers.com/nginx-caching/)) para mejorar enormemente la velocidad y el rendimiento de tu aplicación. + +### Usar un balanceador de carga + +No importa cuán optimizada sea una aplicación, una sola instancia puede manejar sólo una cantidad limitada de carga y tráfico. Una forma de escalar una aplicación es ejecutar múltiples instancias de ella y distribuir el tráfico a través de un equilibrador de carga. Configurar un balanceador de carga puede mejorar el rendimiento y la velocidad de tu aplicación, y permitirla escalar más de lo posible con una sola instancia. + +Un balanceador de carga es generalmente un proxy inverso que orchestriza tráfico hacia y desde múltiples instancias y servidores de la aplicación. Puedes configurar fácilmente un equilibrador de carga para tu aplicación usando [Nginx](https://nginx.org/en/docs/http/load_balancing) o [HAProxy](https://www.digitalocean.com/community/tutorials/an-introduction-to-haproxy-and-load-balancing-concepts). + +Con el saldo de carga, puede que tenga que asegurarse de que las peticiones que están asociadas con un ID de sesión particular se conectan al proceso que las originó. Esto se conoce como _session affinity_, o _sticky sessions_, y puede ser abordado por la sugerencia anterior de utilizar un almacén de datos como Redis para datos de sesión (dependiendo de su aplicación). Para una discusión, vea [Usando múltiples nodos](https://socket.io/docs/v4/using-multiple-nodes/). + +### Usar un proxy inverso + +Un proxy inverso se sienta frente a una aplicación web y realiza operaciones de soporte en las peticiones, además de dirigir peticiones a la aplicación. Puede manejar páginas de errores, compresión, caché, servir archivos y equilibrar la carga entre otras cosas. + +La entrega de tareas que no requieren conocimiento del estado de la aplicación a un proxy inverso libera Express para realizar tareas especializadas de la aplicación. Por esta razón, se recomienda ejecutar Express detrás de un proxy inverso como [Nginx](https://www.nginx.org/) o [HAProxy](https://www.haproxy.org/) en producción. diff --git a/src/content/pages/es/advanced/best-practice-security.mdx b/src/content/pages/es/advanced/best-practice-security.mdx new file mode 100644 index 0000000000..4e270ab3ad --- /dev/null +++ b/src/content/pages/es/advanced/best-practice-security.mdx @@ -0,0 +1,276 @@ +--- +title: "Mejores prácticas de producción: seguridad" +description: Descubra las mejores prácticas de seguridad cruciales para aplicaciones Express en producción, incluyendo el uso de TLS, validación de entradas, cookies seguras y la prevención de vulnerabilidades. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +El término *"producción"* se refiere a la etapa del ciclo de vida del software cuando una aplicación o API está generalmente disponible para sus usuarios finales o consumidores. En contraste, en la etapa *"desarrollo"* todavía estás escribiendo activamente y probando código, y la aplicación no está abierta al acceso externo. Los entornos del sistema correspondientes se conocen como entornos *production* y *development*, respectivamente. + +Los entornos de desarrollo y producción suelen establecerse de forma diferente y tienen requisitos muy diferentes. Lo que está bien en desarrollo puede no ser aceptable en la producción. Por ejemplo, en un entorno de desarrollo puede querer un registro detallado de errores para la depuración, mientras que el mismo comportamiento puede convertirse en una preocupación de seguridad en un entorno de producción. Y en desarrollo, usted no necesita preocuparse por la escalabilidad, fiabilidad y rendimiento, mientras que esas preocupaciones se vuelven críticas en la producción. + + + +Si cree que ha descubierto una vulnerabilidad de seguridad en Express, consulte Seguridad +Políticas y procedimientos. + + + +Las mejores prácticas de seguridad para aplicaciones Express en producción incluyen: + +* [Prácticas Mejores de Producción: Seguridad](#production-best-practices-security) + * [Overview](#overview) + * [No usar versiones obsoletas o vulnerables de Express](#dont-use-deprecated-or-vulnerable-versions-of-express) + * [Usar TLS](#use-tls) + * [No confiar en la entrada del usuario](#do-not-trust-user-input) + * [Prevenir redirecciones abiertas](#prevent-open-redirects) + * [Casco de Uso](#use-helmet) + * [Reducir la huella dactilar](#reduce-fingerprinting) + * [Usar cookies de forma segura](#use-cookies-securely) + * [No usar el nombre de cookie de sesión predeterminado](#dont-use-the-default-session-cookie-name) + * [Establecer opciones de seguridad de cookies](#set-cookie-security-options) + * [Prevenir ataques de fuerza bruta contra autorización](#prevent-brute-force-attacks-against-authorization) + * [Asegúrate de que tus dependencias son seguras](#ensure-your-dependencies-are-secure) + * [Evitar otras vulnerabilidades conocidas](#avoid-other-known-vulnerabilities) + * [Examen adicional](#additional-considerations) + +## No utilizar versiones obsoletas o vulnerables de Express + +Las exprés 2.x y 3.x ya no están mantenidas. No se solucionarán problemas de seguridad y rendimiento en estas versiones. ¡No los utilices! Si no has movido a la versión 4, sigue la [guía de migración](/en/guide/migrating-4) o considera [Opciones de Soporte Comercial](/en/support#commercial-support-options). + +También asegúrese de que no está usando ninguna de las versiones Express vulnerables listadas en la [página de actualizaciones de seguridad](/en/advanced/security-updates). Si lo está, actualice a una de las versiones estables, preferiblemente la más reciente. + +## Usar TLS + +Si tu aplicación trata o transmite datos confidenciales, usa [Seguridad de la capa de transporte](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) para asegurar la conexión y los datos. Esta tecnología encripta los datos antes de que sean enviados desde el cliente al servidor, evitando así algunos hacks comunes (y fáciles). Aunque las solicitudes Ajax y POST pueden no ser visiblemente obvias y parecen "ocultas" en los navegadores, su tráfico de red es vulnerable a [sniffing de paquetes](https://en.wikipedia.org/wiki/Packet_analyzer) y [ataques man-in-the-midds](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). + +Puede estar familiarizado con el cifrado de la capa de conector seguro (SSL). [TLS es simplemente la siguiente progresión de SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). En otras palabras, si estaba usando SSL antes, considere actualizar a TLS. En general, recomendamos Nginx para manejar TLS. Para una buena referencia para configurar TLS en Nginx (y otros servidores), vea [Configuraciones Recomendadas del servidor (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). + +Además, una útil herramienta para obtener un certificado TLS gratis es [Vamos a cifrar](https://letsencrypt.org/about/), un gratuito, automatizado, y autoridad certificadora abierta (CA) proporcionada por el [Grupo de Investigación sobre Seguridad de Internet (ISRG)](https://www.abetterinternet.org/). + +## No confiar en la entrada del usuario + +Para aplicaciones web, uno de los requisitos de seguridad más importantes es la validación y manejo de entrada de usuario apropiados. Esto viene en muchas formas y no vamos a abarcar todas ellas. +En última instancia, la responsabilidad de validar y manejar correctamente los tipos de entrada de usuario que su aplicación acepta es suya. + +### Evitar redirecciones abiertas + +Un ejemplo de entrada de usuario potencialmente peligrosa es una *open redirect*, donde una aplicación acepta una URL como entrada de usuario (a menudo en la consulta de URL, por ejemplo `? rl=https://ejemplo. om`) y usa `res.redirect` para establecer la cabecera `location` y +devuelve un estado de 3xx. + +Una aplicación debe validar que soporta redirección a la URL entrante para evitar enviar usuarios a enlaces maliciosos como sitios web de phishing, entre otros riesgos. + +Aquí hay un ejemplo de comprobación de URLs antes de usar `res.redirect` o `res.location`: + +```js +app.use((req, res) => { + prueba { + if (new Url(req. uery.url).host !== 'ejemplo.com') { + return res.status(400). nd(`Unsupported redirect to host: ${req.query.url}`); + } + } catch (e) { + return res. tatus(400).end(`URL inválida: ${req.query.url}`); + } + res.redirect(req.query.url); +}); +``` + +## Usar Casco + +[Helmet][helmet] puede ayudar a proteger tu aplicación de algunas vulnerabilidades web conocidas configurando los encabezados HTTP adecuadamente. + +Helmet es una función middleware que establece cabeceras de respuesta HTTP relacionadas con la seguridad. El casco establece las siguientes cabeceras por defecto: + +* `Content-Security-Policy`: Una poderosa lista de permisos de lo que puede pasar en tu página que mitiga muchos ataques +* `Cross-Origin-Opener-Policy`: Ayuda a procesar su página aislada +* `Cross-Origin-Resource-Policy`: bloquea que otros carguen sus recursos de origen cruzado +* `Origin-Agent-Cluster`: Cambia el aislamiento del proceso para ser basado en el origen +* `Política de referido`: Controla el encabezado [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) +* `Strict-Transport-Security`: Indica a los navegadores que prefieran HTTPS +* `X-Content Type-Options`: Evita [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +* `X-DNS-Prefetch-Control`: Controla la prebúsqueda DNS +* `X-Download-Options`: Fuerza a guardar las descargas (sólo Internet Explorer) +* `X-Frame-Options`: encabezado antiguo que mitiga ataques [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) +* `X-Permitted-Cross-Domain-Policies`: Controla el comportamiento entre dominios para los productos de Adobe, como Acrobat +* `X-Powered-Por`: Información sobre el servidor web. Eliminado porque puede ser usado en ataques simples +* `X-XSS-Protection`: Encabezado antiguo que intenta mitigar [Ataques XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), pero empeora las cosas, así que Helmet lo deshabilita + +Cada cabecera puede ser configurada o deshabilitada. Para leer más al respecto, por favor vaya a [su sitio web de documentación][helmet]. + +Instalar casco como cualquier otro módulo: + +```bash +$ npm install helmet +``` + +Luego para usarlo en tu código: + +```js +// ... + +const helmet = require('helmet'); +app.use(helmet()); + +// ... +``` + +## Reduce la toma de huellas digitales + +Puede ayudar a proporcionar una capa extra de seguridad para reducir la capacidad de los atacantes para determinar +el software que utiliza un servidor. conocido como "huella dactilar". Aunque no es un problema de seguridad en sí mismo, +reducir la capacidad de huellas dactilares de una aplicación mejora su posición general de seguridad. +El software del servidor puede ser tomado con huellas dactilares en cómo responde a peticiones específicas, por ejemplo en +las cabeceras de respuesta HTTP. + +Por defecto, Express envía la cabecera de respuesta `X-Powered-By` que puede +desactivar usando el método `app.disable()`: + +```js +app.disable('x-powered-by'); +``` + + + +Deshabilitar la \`cabecera X-Powered-By no impide que un atacante sofisticado determine +que una aplicación está ejecutando Express. It may discourage a casual exploit, but there are other ways to +determine an app is running Express. + + + +Express también envía sus propios mensajes de respuesta con formato "404 No encontrados" y de error de formato +. Estos pueden ser cambiados por +[agregando tu propio gestor de error](/en/starter/faq#how-do-i-handle-404-responses) +y +[escribiendo tu propio gestor de error](/en/guide/error-handling#writing-error-handlers): + +```js +// último app.use llama justo antes de app.listen(): + +// custom 404 +app.use((req, res, next) => { + res.status(404). end("¡Lo sentimos no puede encontrar eso!"); +}); + +// manejador de errores personalizado +app. se((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Algo roto!'); +}); +``` + +## Usar cookies de forma segura + +Para asegurar que las cookies no abran su aplicación para explotar, no utilice el nombre de la cookie de sesión por defecto y establezca las opciones de seguridad de las cookies apropiadamente. + +Hay dos módulos principales de sesión de cookies de middleware: + +* [express-session](https://www.npmjs.com/package/express-session) que reemplaza `express.session` middleware integrado a Express 3.x. +* [cookie-session](https://www.npmjs.com/package/cookie-session) que reemplaza el middleware `express.cookieSession` integrado a Express 3.x. + +La principal diferencia entre estos dos módulos es cómo guardan los datos de sesión de cookies. El middleware [express-session](https://www.npmjs.com/package/express-session) almacena datos de sesión en el servidor; sólo guarda el ID de sesión en la cookie misma, no los datos de sesión. Por defecto, utiliza almacenamiento en memoria y no está diseñado para un entorno de producción. En producción, necesitarás configurar una tienda de sesiones escalable; consulta la lista de [tiendas de sesiones compatibles](https://github.com/expressjs/session#compatible-session-stores). + +En contraste, [cookie-session](https://www.npmjs.com/package/cookie-session) middleware implementa el almacenamiento respaldado por cookies: serializa toda la sesión a la cookie, en lugar de solo una clave de sesión. Sólo usarlo cuando los datos de sesión son relativamente pequeños y fácilmente codificados como valores primitivos (en lugar de objetos). Aunque los navegadores deben soportar al menos 4096 bytes por cookie, para asegurarse de que no exceda el límite, no exceda un tamaño de 4093 bytes por dominio. Además, tenga en cuenta que los datos de las cookies serán visibles para el cliente, así que si hay alguna razón para mantenerlo seguro u oscuro, entonces `express-session` puede ser una mejor elección. + +### No utilizar el nombre predeterminado de la cookie de sesión + +Usar el nombre de la cookie de sesión por defecto puede abrir su aplicación para atacar. El problema de seguridad planteado es similar al de `X-Powered-Por`: un atacante potencial puede usarlo para tomar las huellas dactilares del servidor y atacar en consecuencia. + +To avoid this problem, use generic cookie names; for example using [express-session](https://www.npmjs.com/package/express-session) middleware: + +```js +const session = require('express-session'); +app.set('trust proxy', 1); // confíe en primer proxy +aplicación. se( + session({ + secret: 's3Cur3', + name: 'sessionId', + }) +); +``` + +### Configurar opciones de seguridad de cookies + +Establecer las siguientes opciones de cookie para mejorar la seguridad: + +* `secure` - Asegura que el navegador sólo envía la cookie a través de HTTPS. +* `httpOnly` - Asegura que la cookie se envía sólo sobre HTTP(S), no sobre JavaScript del cliente, ayudando a proteger contra ataques de cross-site scripting. +* `domain` - indica el dominio de la cookie; úselo para comparar con el dominio del servidor en el que se solicita la URL. Si coinciden, entonces marque el atributo de ruta siguiente. +* `path` - indica la ruta de la cookie; úsala para comparar la ruta de la solicitud. Si esto y el dominio coinciden, entonces envíe la cookie en la solicitud. +* `expires` - usa para fijar la fecha de caducidad de las cookies persistentes. + +Aquí hay un ejemplo usando un middleware [cookie-session](https://www.npmjs.com/package/cookie-session): + +```js +const session = require('cookie-session'); +const express = require('express'); +const app = express(); + +const expiryDate = new Date(Date. ow() + 60 * 60 * 1000); // 1 hora +aplicación. se( + session({ + name: 'session', + keys: ['key1', 'key2'], + cookie: { + secure: true, + httpOnly: true, + dominio: 'ejemplo. om', + ruta: 'foo/bar', + expires: expiryDate, + }, + }) +); +``` + +## Evitar ataques de fuerza bruta contra autorización + +Asegúrese de que los puntos finales de inicio de sesión están protegidos para hacer que los datos privados sean más seguros. + +Una técnica simple y poderosa es bloquear los intentos de autorización utilizando dos métricas: + +1. El número de intentos fallidos consecutivos por el mismo nombre de usuario y dirección IP. +2. El número de intentos fallidos de una dirección IP durante un largo período de tiempo. Por ejemplo, bloquee una dirección IP si hace 100 intentos fallidos en un día. + +Un paquete [rate-limiter-flexible](https://github.com/animir/node-rate-limiter-flexible) proporciona herramientas para hacer esta técnica fácil y rápida. Puedes encontrar [un ejemplo de protección de fuerza bruta en la documentación](https://github.com/animir/node-rate-limiter-flexible/wiki/Overall-example#login-endpoint-protection) + +## Asegúrate de que tus dependencias son seguras + +Usar npm para administrar las dependencias de tu aplicación es potente y conveniente. Pero los paquetes que usa pueden contener vulnerabilidades de seguridad críticas que también podrían afectar a su aplicación. La seguridad de tu aplicación es tan fuerte como el "enlace más débil" en tus dependencias. + +Desde npm@6, npm revisa automáticamente cada solicitud de instalación. También, puede usar `npm audit` para analizar su árbol de dependencias. + +```bash +$ npm auditoría +``` + +Si quieres estar más seguro, considera [Snyk](https://snyk.io/). + +Snyk ofrece una [herramienta de línea de comandos](https://www.npmjs.com/package/snyk) y una [integración de Github](https://snyk.io/docs/github) que comprueba tu aplicación contra [la base de datos de vulnerabilidad de código abierto de Snyk](https://snyk.io/vuln/) para cualquier vulnerabilidad conocida en tus dependencias. Instalar el CLI de la siguiente manera: + +```bash +$ npm install -g snyk +$ cd tu-app +``` + +Utilice este comando para probar las vulnerabilidades de su aplicación: + +```bash +$ prueba de snyk +``` + +### Evitar otras vulnerabilidades conocidas + +Esté atento a los avisos de [Node Security Project](https://npmjs.com/advisories) o [Snyk](https://snyk.io/vuln/) que pueden afectar a Express u otros módulos que tu aplicación utiliza. En general, estas bases de datos son excelentes recursos para conocimientos y herramientas sobre la seguridad de Node. + +Finalmente, las aplicaciones Express—como cualquier otra aplicación web—pueden ser vulnerables a una variedad de ataques basados en la web. Familiarizarse con [vulnerabilidades web](https://www.owasp.org/www-project-top-ten/) y tomar precauciones para evitarlas. + +## Consideraciones adicionales + +Estas son algunas recomendaciones adicionales de la excelente [Lista de verificación de seguridad de Node.js](https://blog.risingstack.com/node-js-security-checklist/). Consulte esa entrada para ver todos los detalles de estas recomendaciones: + +* Siempre filtrar y limpiar la entrada del usuario para proteger contra ataques de cross-site scripting (XSS) e inyección de comandos. +* Defienda contra ataques de inyección de SQL usando consultas parametrizadas o sentencias preparadas. +* Utilice la herramienta de código abierto [sqlmap](http://sqlmap.org/) para detectar vulnerabilidades de inyección SQL en su aplicación. +* Utilice las herramientas [nmap](https://nmap.org/) y [sslyze](https://github.com/nabla-c0d3/sslyze) para probar la configuración de sus cifrados SSL, llaves, renegociación, así como la validez de su certificado. +* Usa [safe-regex](https://www.npmjs.com/package/safe-regex) para asegurar que tus expresiones regulares no sean susceptibles a los ataques de [denegación de expresión regular de servicio](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS). + +[helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/es/advanced/healthcheck-graceful-shutdown.md b/src/content/pages/es/advanced/healthcheck-graceful-shutdown.md new file mode 100644 index 0000000000..bb0926aaa2 --- /dev/null +++ b/src/content/pages/es/advanced/healthcheck-graceful-shutdown.md @@ -0,0 +1,28 @@ +--- +title: Comprobaciones de salud y apagado positivo +description: Aprende cómo implementar comprobaciones de salud y apagado con gracia en aplicaciones Express para mejorar la confiabilidad, administrar implementaciones e integrarse con equilibradores de carga como Kubernetes. +--- + +## Apagado controlado + +Cuando despliegues una nueva versión de tu aplicación, debes reemplazar la versión anterior. El gestor de procesos que está utilizando enviará primero una señal de SIGTERM a la aplicación para notificarle que será asesinado. Una vez que la aplicación reciba esta señal, debería dejar de aceptar nuevas solicitudes, terminar todas las solicitudes en curso, limpiar los recursos que utilizó, incluyendo conexiones de base de datos y bloqueos de archivos y luego salir. + +### Ejemplo + +```js +const server = app.listen(port); + +process.on('SIGTERM', () => { + debug('SIGTERM signal received: closing HTTP server'); + server.close(() => { + debug('HTTP server closed'); + }); +}); +``` + +## Revisiones de salud + +Un balanceador de carga utiliza cheques de salud para determinar si una instancia de aplicación es saludable y puede aceptar solicitudes. Por ejemplo, [Kubernetes tiene dos cheques de salud](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/): + +- `liveness`, que determina cuándo reiniciar un contenedor. +- `readiness`, que determina cuando un contenedor está listo para empezar a aceptar tráfico. Cuando un pod no está listo, se elimina de los balanceadores de carga de servicio. diff --git a/src/content/pages/es/advanced/security-updates.mdx b/src/content/pages/es/advanced/security-updates.mdx new file mode 100644 index 0000000000..afe751197e --- /dev/null +++ b/src/content/pages/es/advanced/security-updates.mdx @@ -0,0 +1,87 @@ +--- +title: Actualización de seguridad +description: Revise las últimas actualizaciones de seguridad y los parches de Express.js, incluyendo listas detalladas de vulnerabilidades para diferentes versiones para ayudar a mantener una aplicación segura. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Las vulnerabilidades de Node.js afectan directamente a Express. Por lo tanto, vigila Node.js +vulnerabilidades y asegúrate de que estás usando la última versión +estable de Node.js. + + + +La siguiente lista enumera las vulnerabilidades Express que se corrigieron en la actualización de versión especificada. + + + +Si cree que ha descubierto una vulnerabilidad de seguridad en Express, consulte Seguridad +Políticas y procedimientos. + + + +## 4 x + +* 4.21.2 + * La dependencia `path-to-regexp` ha sido actualizada para direccionar un [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +* 4.21.1 + * La dependencia `cookie` ha sido actualizada para dirigirse a una [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), Esto puede afectar a tu aplicación si utilizas `res.cookie`. +* 4.20.0 + * Se corrigió la vulnerabilidad XSS en `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + * La dependencia `serve-static` ha sido actualizada para direccionar un [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). + * La dependencia `send` ha sido actualizada para direccionar un [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + * La dependencia `path-to-regexp` ha sido actualizada para direccionar un [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + * La dependencia `body-parser` ha sido actualizada para montar un [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), Esto puede afectar a tu aplicación si tenías activada la conexión url. +* 4.19.0, 4.19.1 + * Corregida vulnerabilidad de redirección abierta en `res.location` y `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +* 4.17.3 + * La dependencia `qs` ha sido actualizada para direccionar un [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). Esto puede afectar a su aplicación si se utilizan las siguientes API: `req.query`, `req.body`, `req.param`. +* 4.16.0 + * La dependencia `forwarded` ha sido actualizada para direccionar un [vulnerability](https://npmjs.com/advisories/527). Esto puede afectar a su aplicación si se utilizan las siguientes API: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + * La dependencia `mime` ha sido actualizada para abordar un [vulnerability](https://npmjs.com/advisories/535), pero este problema no afecta a Express. + * La dependencia `send` ha sido actualizada para proporcionar una protección contra una [vulnerabilidad de Node.js 8.5.0](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). Esto sólo afecta a la ejecución de Express en la versión 8.5.0 específica de Node.js. +* 4.15.5 + * La dependencia `debug` ha sido actualizada para abordar un [vulnerability](https://snyk.io/vuln/npm:debug:20170905), pero este problema no afecta a Express. + * La dependencia `fresh` ha sido actualizada para direccionar un [vulnerability](https://npmjs.com/advisories/526). Esto afectará a tu aplicación si se utilizan las siguientes API: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. +* 4.15.3 + * La dependencia `ms` ha sido actualizada para direccionar un [vulnerability](https://snyk.io/vuln/npm:ms:20170412). Esto puede afectar a tu aplicación si la entrada de cadena no confiable es pasada a la opción `maxAge` en las siguientes APIs: `express.static`, `res.sendfile`, y `res.sendFile`. +* 4.15.2 + * La dependencia `qs` ha sido actualizada para abordar un [vulnerability](https://snyk.io/vuln/npm:qs:20170213), pero este problema no afecta a Express. Actualizar a 4.15.2 es una buena práctica, pero no es necesario para abordar la vulnerabilidad. +* 4.11.1 + * Se corrigió la vulnerabilidad de revelación de ruta de root en `express.static`, `res.sendfile`, y `res.sendFile` +* 4.10.7 + * Se corrigió la vulnerabilidad de redirección abierta en `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 4.8.8 + * Se corrigieron vulnerabilidades de recorrido de directorio en `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +* 4.8.4 + * Node.js 0.10 puede filtrar `fd`s en ciertas situaciones que afectan `express.static` y `res.sendfile`. Las peticiones maliciosas podrían causar que `fd`s se filtrara y eventualmente llevar a `EMFILE` errores y la falta de respuesta del servidor. +* 4.8.0 + * Las matrices Sparse que tienen índices extremadamente altos en la cadena de consultas podrían causar que el proceso se quedara sin memoria y cayera el servidor. + * Los objetos de cadena de consulta anidados pueden causar que el proceso bloquee y haga que el servidor no responda temporalmente. + +## 3.x + + +**Express 3.x está END-OF-LIFE Y NINGUNA LONGERA MAINTADA** + +Los problemas de seguridad y rendimiento conocidos y desconocidos en 3.x no han sido abordados desde la última actualización (1 de agosto de 2015). Es altamente recomendable utilizar la última versión de Express. + +Si no puedes actualizar más allá de 3.x, por favor considera [Opciones de Soporte Comercial](/en/support#commercial-support-options). + + + +* 3.19.1 + * Se corrigió la vulnerabilidad de revelación de ruta de root en `express.static`, `res.sendfile`, y `res.sendFile` +* 3.19.0 + * Se corrigió la vulnerabilidad de redirección abierta en `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 3.16.10 + * Se corrigieron vulnerabilidades de recorrido de directorio en `express.static`. +* 3.16.6 + * Node.js 0.10 puede filtrar `fd`s en ciertas situaciones que afectan `express.static` y `res.sendfile`. Las peticiones maliciosas podrían causar que `fd`s se filtrara y eventualmente llevar a `EMFILE` errores y la falta de respuesta del servidor. +* 3.16.0 + * Las matrices Sparse que tienen índices extremadamente altos en la cadena de consultas podían causar que el proceso se quedara sin memoria y cayera el servidor. + * Los objetos de cadena de consulta anidados pueden causar que el proceso bloquee y haga que el servidor no responda temporalmente. +* 3.3.0 + * La respuesta 404 de un intento de anulación de método no soportado era susceptible a ataques de cross-site scripting. diff --git a/src/content/pages/es/guide/database-integration.mdx b/src/content/pages/es/guide/database-integration.mdx new file mode 100644 index 0000000000..7d64d12df7 --- /dev/null +++ b/src/content/pages/es/guide/database-integration.mdx @@ -0,0 +1,503 @@ +--- +title: Integración de la base de datos +description: Descubra cómo integrar varias bases de datos con aplicaciones Express.js, incluyendo ejemplos de configuración para MongoDB, MySQL, PostgreSQL, y más. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Añadir la capacidad para conectar bases de datos a aplicaciones Express es sólo una cuestión de cargar un controlador Node.js apropiado para la base de datos en su aplicación. Este documento explica brevemente cómo agregar y utilizar algunos de los módulos Node.js más populares para sistemas de base de datos en su aplicación Express: + +* [Cassandra](#cassandra) +* [Couchbase](#couchbase) +* [CouchDB](#couchdb) +* [LevelDB](#leveldb) +* [MySQL](#mysql) +* [MongoDB](#mongodb) +* [Neo4j](#neo4j) +* [Oracle](#oracle) +* [PostgreSQL](#postgresql) +* [Redis](#redis) +* [Servidor SQL](#sql-server) +* [SQLite](#sqlite) +* [Elasticsearch](#elasticsearch) + + + +Estos controladores de base de datos están entre muchos que están disponibles. Para otras opciones, busca en el sitio +[npm](https://www.npmjs.com/). + + + +## Cassandra + +**Módulo**: [cassandra-driver](https://github.com/datastax/nodejs-driver) + +### Instalación + +```bash +$ npm install cassandra-driver +``` + +### Ejemplo + +```js +const cassandra = require('cassandra-driver'); +const client = new cassandra.Client({ contactPoints: ['localhost'] }); + +client. xecute('select key from system.local', (err, result) => { + if (err) throw err; + console.log(result.rows[0]); +}); +``` + +## Couchbase + +**Módulo**: [couchnode](https://github.com/couchbase/couchnode) + +### Instalación + +```bash +$ npm install couchbase +``` + +### Ejemplo + +```js +const couchbase = require('couchbase'); +const bucket = new couchbase.Cluster('http://localhost:8091').openBucket('bucketName'); + +// añade un documento al cubo +bucket. nsert('document-key', { name: 'Matt', shoeSize: 13 }, (err, result) => { + if (err) { + consola. og(err); + } else { + consola. og(result); + } +}); + +// obtener todos los documentos con el tamaño de zapato 13 +const n1ql = 'SELECT d. FROM `bucketName` d WHERE shoeSize = $1'; +const query = N1qlQuery. romString(n1ql); +bucket.query(query, [13], (err, result) => { + if (err) { + consola. og(err); + } else { + console.log(result); + } +}); +``` + +## CouchDB + +**Módulo**: [nano](https://github.com/dscape/nano) + +### Instalación + +```bash +$ npm install nano +``` + +### Ejemplo + +```js +const nano = require('nano')('http://localhost:5984'); +nano.db.create('books'); +const books = nano.db. se('books'); + +// Inserta un documento de libro en la base de datos de libros +libros. nsert({ name: 'The Art of war' }, null, (err, body) => { + if (err) { + console. og(err); + } else { + consola. og(body); + } +}); + +// Obtén una lista de todos los libros +libros. ist((err, body) => { + if (err) { + consola. og(err); + } else { + console.log(body.rows); + } +}); +``` + +## LevelDB + +**Módulo**: [levelup](https://github.com/rvagg/node-levelup) + +### Instalación + +```bash +$ npm instalar nivel de nivelación +``` + +### Ejemplo + +```js +const levelup = require('levelup'); +const db = levelup('./mydb'); + +db. ut('nombre', 'LevelUP', (err) => { + if (err) return console.log('¡Ooops!', err); + + db. et('nombre', (err, value) => { + if (err) return consola. og('¡Ooops!', err); + + console.log(`name=${value}`); + }); +}); +``` + +## MySQL + +**Módulo**: [mysql](https://github.com/felixge/node-mysql/) + +### Instalación + +```bash +$ npm install mysql +``` + +### Ejemplo + +```js +const (0)[video] ql = require('mañql'); +const connection = .Uql. reateConnection({ + host: 'localhost', + user: 'dbuser', + password: 's3kreee7', + database: 'my_db', +}); + +conexión. onnect(); + +connection.query('SELECT 1 + 1 AS solution', (err, filas, campos) => { + if (err) throw err; + + consola. og('La solución es: ', filas[0].solution); +}); + +connection.end(); +``` + +## MongoDB + +**Módulo**: [mongodb](https://github.com/mongodb/node-mongodb-native) + +### Instalación + +```bash +$ npm install mongodb +``` + +### Ejemplo (v2.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { + if (err) throw err; + + db. ollection('mammals') + .find() + . oArray((err, result) => { + if (err) throw err; + + consola. og(resultado); + }); +}); +``` + +### Ejemplo (v3.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, client) => { + if (err) throw err; + + const db = client. b('animales'); + + db.collection('mammals') + .find() + . oArray((err, result) => { + if (err) throw err; + + consola. og(resultado); + }); +}); +``` + +Si quieres un controlador de modelo de objeto para MongoDB, mira [Mongoose](https://github.com/LearnBoost/mongoose). + +## Neo4j + +**Módulo**: [neo4j-driver](https://github.com/neo4j/neo4j-javascript-driver) + +### Instalación + +```bash +$ npm install neo4j-driver +``` + +### Ejemplo + +```js +const neo4j = require('neo4j-driver'); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth. asic('neo4j', 'letmein')); + +const session = driver.session(); + +session.readTransaction((tx) => { + return tx + . un('MATCH (n) RETURN count(n) AS count') + .then((res) => { + console.log(res.records[0]. et('count')); + }) + .catch((error) => { + consola. og(error); + }); +}); +``` + +## Oráculo + +**Módulo**: [oracledb](https://github.com/oracle/node-oracledb) + +### Instalación + +NOTA: [Ver los prerrequisitos de instalación](https://github.com/oracle/node-oracledb#-installation). + +```bash +$ npm install oracledb +``` + +### Ejemplo + +```js +const oracledb = require('oracledb'); +const config = { + user: '', + password: '', + connectString: 'localhost:1521/orcl', +}; + +async function getEmployee(empId) { + let conn; + + try { + conn = await oracledb. etConnection(config); + + const result = await conn. xecute('select * from employees where employee_id = :id', [empId]); + + consola. og(result.rows[0]); + } catch (err) { + consola. og('¡Og! , err); + } finally { + if (conn) { + // asignación conn trabajada, necesitan cerrar + esperando conn. lose(); + } + } +} + +getEmployee(101); +``` + +## PostgreSQL + +**Módulo**: [pg-promise](https://github.com/vitaly-t/pg-promise) + +### Instalación + +```bash +$ npm install pg-promise +``` + +### Ejemplo + +```js +const pgp = require('pg-promise')(/* options */); +const db = pgp('postgres://username:password@host:port/database'); + +db.one('SELECT $1 AS value', 123) + . hen((data) => { + console.log('DATA:', data.value); + }) + . atch((error) => { + console.log('ERROR:', error); +}); +``` + +## Redis + +**Módulo**: [redis](https://github.com/mranney/node_redis) + +### Instalación + +```bash +$ npm install redis +``` + +### Ejemplo + +```js +const redis = require('redis'); +const client = redis.createClient(); + +client.on('error', (err) => { + console.log(`Error ${err}`); +}); + +cliente. et('clave de cadena', 'valor de cadena', redis.print); +client.hset('clave hash', 'hashtest 1', 'some value', redis.print); +cliente. set(['hash key', 'hashtest 2', 'algún otro valor'], redis.print); Cliente + +. keys('clave hash', (err, respuestas) => { + console.log(`${replies.length} respuestas:`); + + respuestas. orEach((reply, i) => { + consola. og(` ${i}: ${reply}`); + }); + + client.quit(); +}); +``` + +## SQL Server + +**Módulo**: [tedious](https://github.com/tediousjs/tedious) + +### Instalación + +```bash +$ npm install tedious +``` + +### Ejemplo + +```js +const Connection = require('tedious').Connection; +const Request = require('tedious'). equest; + +const config = { + server: 'localhost', + autenticación: { + type: 'default', + opciones: { + userName: 'su_usuario', // actualizarme + contraseña: 'su_contraseña', // actualizarme + }, + }, +}; + +const connection = new Connection(config); + +connection. n('connect', (err) => { + if (err) { + consola. og(err); + } else { + executeStatement(); + } +}); + +function executeStatement() { + request = new Request("select 123, 'hola mundo'", (err, rowCount) => { + if (err) { + consola. og(err); + } else { + consola. og(`${rowCount} filas`); + } + conexión. lose(); + }); + + request.on('fila', (columnas) => { + columnas. orEach((column) => { + if (column.value === null) { + consola. og('NULL'); + } else { + console.log(column. alue); + } + }); + }); + + connection.execSql(request); +} +``` + +## SQLite + +**Módulo**: [sqlite3](https://github.com/mapbox/node-sqlite3) + +### Instalación + +```bash +$ npm install sqlite3 +``` + +### Ejemplo + +```js +const sqlite3 = require('sqlite3').verbose(); +const db = new sqlite3.Database(':memory:'); + +db.serialize(() => { + db. un('CREATE TABLE lorem (info TEXT)'); + const stmt = db. repare('INSERT INTO Lorem VALUES (?)'); + + for (let i = 0; i < 10; i++) { + stmt. un(`Ipsum ${i}`); + } + + stmt.finalize(); + + db. ach('SELECT rowid AS id, info FROM lorem', (err, row) => { + consola. og(`${row.id}: ${row.info}`); + }); +}); + +db.close(); +``` + +## Búsqueda elástica + +**Módulo**: [elasticsearch](https://github.com/elastic/elasticsearch-js) + +### Instalación + +```bash +$ npm instalar elasticsearch +``` + +### Ejemplo + +```js +const elasticsearch = require('elasticsearch'); +const client = elasticsearch.Client({ + host: 'localhost:9200', +}); + +client + . earch({ + index: 'libros', + tipo: 'libro', + body: { + query: { + multi_match: { + query: 'express js', + campos: ['title', 'description'], + }, + }, + }, + }) + . hen( + (response) => { + const hits = response.hits. its; + }, + (error) => { + consola. race(error.message); + } +); +``` diff --git a/src/content/pages/es/guide/migrating-4.mdx b/src/content/pages/es/guide/migrating-4.mdx new file mode 100644 index 0000000000..445b2e8bf2 --- /dev/null +++ b/src/content/pages/es/guide/migrating-4.mdx @@ -0,0 +1,662 @@ +--- +title: Moviendo a Express 4 +description: Una guía para migrar sus aplicaciones Express.js de la versión 3 a 4, que cubre los cambios en middleware, routing, y cómo actualizar su código base efectivamente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express 4 es un cambio de ruptura de Express 3. Esto significa que una aplicación Express 3 funcionará *no* si actualiza la versión Express en sus dependencias. + +Este artículo cubre: + + + +## Cambios en Express 4 + +Hay varios cambios significativos en Express 4: + + + +Ver también: + +* [Nuevas características en 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +* [Migración de 3.x a 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) + +### Cambios al sistema Express core y middleware + +Express 4 ya no depende de Connect, y elimina todo el Middleware integrado +de su núcleo, excepto la función `express.static`. Esto significa que +Express es ahora un entorno web independiente de enrutamiento y middleware. y +Las versiones y versiones exprés no se ven afectadas por las actualizaciones de middleware. + +Sin middleware integrado, debe agregar explícitamente todo el Middleware +que es necesario para ejecutar su aplicación. Simplemente sigue estos pasos: + +1. Instala el módulo: `npm install --save ` +2. En tu aplicación, requiere el módulo: `require('module-name')` +3. Utilice el módulo de acuerdo a su documentación: `app.use( ... )` + +La siguiente tabla muestra Express 3 middleware y sus contrapartes en Express 4. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Express 3Express 4
+ express.bodyParser + + body-parser + + multer +
+ express.compresione + + compresión +
+ express.cookieSession + + sesión de galletas +
+ express.cookieParser + + parser cookie- +
+ express.logger + + morgan +
+ express.session + + express-sesión +
+ express.favicon + + serve-favicon +
+ express.responseTime + + tiempo de respuesta +
+ express.errorHandler + + errorhandler +
+ express.methodOverride + + sobrescribir método +
+ express.timeout + + tiempo de espera de conexión +
+ express.vhost + + vhost +
+ express.csrf + + csurf +
+ express.directory + + serve-index +
+ express.static + + serve-static +
+ +Aquí está la [lista completa](https://github.com/senchalabs/connect#middleware) de Middleware Express 4. + +En la mayoría de los casos, puede reemplazar el middleware de la versión 3 anterior por +su contraparte Express 4. Para más detalles, consulte la documentación del módulo en +GitHub. + +#### `app.use` acepta parámetros + +En la versión 4 se puede utilizar un parámetro variable para definir la ruta donde se cargan las funciones de middleware, entonces lea el valor del parámetro del gestor de rutas. +Por ejemplo: + +```js +app.use('/book/:id', (req, res, next) => { + console.log('ID:', req.params.id); + next(); +}); +``` + +### El sistema de enrutamiento + +Aplicaciones ahora cargan implícitamente middleware de ruta, así que ya no tienes que preocuparte por +del orden en el que el middleware está cargado con respecto a +el middleware `router`. + +La forma en que defines las rutas no ha cambiado, pero el sistema de enrutamiento tiene dos características +nuevas para ayudar a organizar tus rutas: + +* Un nuevo método, `app.route()`, para crear manejadores de rutas encadenables para una ruta de ruta. +* Una nueva clase, `express.Router`, para crear manejadores modulares de rutas montables. + +#### método `app.route()` + +El nuevo método `app.route()` le permite crear controladores de rutas encadenables +para una ruta de ruta. Debido a que el camino se especifica en una única ubicación, crear rutas modulares es útil, al igual que reducir redundancia y errores tipográficos. For more +information about routes, see [`Router()` documentation](/en/4x/api#router). + +Aquí hay un ejemplo de manejadores encadenados de rutas que se definen usando la función `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res. end('Obtén un libro al azar'); + }) + . ost((req, res) => { + res.send('Agregar un libro'); + }) + . ut((req, res) => { + res.send('Actualizar el libro'); +}); +``` + +#### Clase `express.Router` + +La otra característica que ayuda a organizar rutas es una nueva clase, +`express.Router`, que puedes usar para crear manejadores de rutas modulares montables +. Una instancia `Router` es un completo middleware y un sistema de enrutamiento +; por esta razón a menudo se le denomina "mini-app". + +El siguiente ejemplo crea un enrutador como módulo, carga middleware en +, define algunas rutas y las monta en una ruta en la aplicación principal. + +Por ejemplo, crea un archivo de enrutador llamado `birds.js` en el directorio de la aplicación, +con el siguiente contenido: + +```js +var express = require('express'); +var router = express.Router(); + +// middleware específico para este router +. se((req, res, next) => { + console.log('Hora: ', Date. ow()); + siguiente(); +}); +// define el router +de la página de inicio. et('/', (req, res) => { + res.send('Página inicial de aves'); +}); +// define la ruta +router. et('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Luego, cargue el módulo de enrutador en la aplicación: + +```js +var birds = require('./birds'); + +// ... + +app.use('/birds', aves); +``` + +La aplicación ahora podrá manejar las solicitudes a las rutas `/birds` y +`/birds/about`, y llamará al middleware `timeLog` +que es específico de la ruta. + +### Otros cambios + +La siguiente tabla muestra otros cambios pequeños pero importantes en Express 4: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ObjetoDescripción
Node.jsExpress 4 requiere Node.js 0.10.x o posterior y ha eliminado el soporte para Node.js 0.8.x.
`http.createServer()` + El módulo `http` ya no es necesario, a menos que necesite trabajar directamente con él + (socket.io/SPDY/HTTPS). La aplicación puede iniciarse usando la función `app.listen()`. +
`app.configure()` + La función `app.configure()` ha sido eliminada. Usa la función `process.env.NODE_ENV` o + `app.get('env')` para detectar el entorno y configurar la aplicación en consecuencia. +
`espacios json` + La propiedad de aplicación `json spaces` está deshabilitada por defecto en Express 4. +
`req.accepted()` + Usa `req.accepts()`, `req.acceptsEncodings()`, `req.acceptsCharsets()`, y + `req.acceptsLanguages()`. +
`res.location()`Ya no resuelve las URL relativas.
`req.params`Era un arreglo; ahora un objeto.
`res.locals`Era una función; ahora un objeto.
`res.headerSent`Cambiado a `res.headersSent`.
`app.route`Ahora disponible como `app.mountpath`.
`res.on('encabezado')`Eliminado.
`res.charset`Eliminado.
`res.setHeader('Set-Cookie', val)` + La funcionalidad ahora se limita a establecer el valor básico de la cookie. Usa `res.cookie()` para añadir funcionalidad + . +
+ +## Ejemplo de migración de aplicación + +He aquí un ejemplo de migración de una aplicación Express 3 a Express 4. +Los archivos de interés son `app.js` y `package.json`. + +### Versión 3 app + +#### `app.js` + +Considere una aplicación Express v.3 con el siguiente archivo `app.js`: + +```js +var express = require('express'); +var routes = require('./routes'); +var user = require('. routes/user'); +var http = require('http'); +var path = require('path'); + +var app = express(); + +// todos los entornos +app. et('puerto', process.env.PORT || 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(express.favicon()); +app.use(express.logger('dev')); +app.use(express.methodOverride()); +app.use(express. ession({ secret: 'your secret here' })); +app.use(express.bodyParser()); +app.use(app.router); +app.use(express. tatic(path.join(__dirname, 'public'))); + +// desarrolla sólo +if (app.get('env') === 'development') { + app. se(express.errorHandler()); +} + +app.get('/', routes.index); +app.get('/users', user.list); + +http. reateServer(app).listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + +#### `package.json` + +El archivo `package.json` de la versión 3 que acompaña podría verse +algo así: + +```json +{ + "name": "application-name", + "version": "0.0. ", + "private": true, + "scripts": { + "start": "node app. " + }, + "dependencies": { + "express": "3. 2.0", + "pug": "*" + } +} +``` + +### Proceso + +Comience el proceso de migración instalando el middleware necesario para la aplicación +Express 4 y actualizando Express y Pug a su respectiva versión +con el siguiente comando: + +```bash +$ npm install serve-favicon morgan method-override express-session body-parser multer errorhandler express@latest pug@latest --save +``` + +Hacer los siguientes cambios a `app.js`: + +1. El middleware Express incorporado funciona `express.favicon`, + `express.logger`, `express.methodOverride`, + `express.session`, `express.bodyParser` y + `express.errorHandler` ya no están disponibles en el objeto + `express`. Debes instalar sus alternativas + manualmente y cargarlas en la aplicación. + +2. Ya no necesitas cargar la función `app.router`. + No es un objeto de aplicación Express 4 válido, por lo que elimina el código + `app.use(app.router);`. + +3. Asegúrese de que las funciones de middleware se cargan en el orden correcto - cargar `errorHandler` después de cargar las rutas de la aplicación. + +### Versión 4 app + +#### `package.json` + +Ejecutar el comando anterior `npm` actualizará `package.json` de la siguiente manera: + +```json +{ + "name": "application-name", + "version": "0.0. ", + "private": true, + "scripts": { + "start": "node app. " + }, + "dependencies": { + "body-parser": "^1.5.2", + "errorhandler": "^1.1. ", + "express": "^4.8.0", + "express-session": "^1. .2", + "pug": "^2.0.0", + "method-override": "^2. .2", + "morgan": "^1.2.2", + "multer": "^0.1. ", + "serve-favicon": "^2.0.1" + } +} +``` + +#### `app.js` + +Luego, elimina el código inválido, carga el middleware necesario y haz otros cambiosformat@@0 +según sea necesario. El archivo `app.js` se verá así: + +```js +var http = require('http'); +var express = require('express'); +var routes = require('./routes'); +var user = require('. routes/usuario'); +var path = require('ruta'); + +var favicon = require('serve-favicon'); +var logger = require('morgan'); +var methodOverride = require('method-override'); +var session = require('express-session'); +var bodyParser = require('body-parser'); +var multer = require('multer'); +var errorHandler = require('errorhandler'); + +var app = express(); + +// todos los entornos +app. et('puerto', process.env.PORT || 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(favicon(path.join(__dirname, '/public/favicon.ico'))); +app.use(logger('dev')); +app. se(methodOverride()); +app. se( + session({ + resave: true, + saveUninitialized: true, + secretos: 'uwotm8', + }) +); +aplicaciones. se(bodyParser.json()); +app.use(bodyParser.urlencoded({ extended: true })); +app.use(multer()); +app.use(express.static(path.join(__dirname, 'public'))); + +app.get('/', rutas. ndex); +app.get('/users', user.list); + +// middleware de manejo de error debe ser cargado después de la carga de las rutas +if (app. et('env') === 'development') { + app. se(errorHandler()); +} + +var server = http.createServer(app); +server.listen(app. et('puerto'), () => { + console.log('Servidor expreso escuchando en el puerto ' + app.get('port')); +}); +``` + + +A menos que necesite trabajar directamente con el módulo `http` (socket.io/SPDY/HTTPS), cargarlo no es necesario, y la aplicación puede iniciarse simplemente de esta manera: + +```js +app.listen(app.get('port'), () => { + console.log('Servidor Express escuchando en el puerto ' + app.get('port')); +}); +``` + + + +### Ejecutar la aplicación + +El proceso de migración se ha completado, y la aplicación es ahora una aplicación +Express 4. Para confirmar, inicia la aplicación usando el siguiente comando: + +```bash +$ nodo . +``` + +Cargar [http://localhost:3000](http://localhost:3000) +y ver la página de inicio mostrada por Express 4. + +## Actualización al generador de aplicaciones Express 4 + +La herramienta de línea de comandos para generar una aplicación Express sigue siendo +`express`, pero para actualizar a la nueva versión, debe desinstalar +el generador de aplicaciones Express 3 y luego instalar el nuevo generador +`express-generator`. + +### Instalando + +Si ya tiene instalado el generador de aplicaciones Express 3 en su sistema, +debe desinstalarlo: + +```bash +$ npm desinstalar -g express +``` + +Dependiendo de cómo estén configurados tus privilegios de archivo y directorio, +puede que necesites ejecutar este comando con `sudo`. + +Ahora instale el nuevo generador: + +```bash +$ npm install -g express-generator +``` + +Dependiendo de cómo estén configurados tus privilegios de archivo y directorio, +puede que necesites ejecutar este comando con `sudo`. + +Ahora el comando `express` en su sistema se actualiza al generador +Express 4. + +### Cambios al generador de aplicaciones + +Las opciones de comando y uso siguen siendo en gran medida las mismas, con las siguientes excepciones: + +* Se ha eliminado la opción `--sessions`. +* Se ha eliminado la opción `--jshtml`. +* Se añadió la opción `--hogan` para soportar [Hogan.js](http://twitter.github.io/hogan.js/). + +### Ejemplo + +Ejecutar el siguiente comando para crear una aplicación Express 4: + +```bash +$ app4 expreso +``` + +Si observas el contenido del archivo `app4/app.js`, notarás +que todas las funciones de middleware (excepto `express. tatic`) que son requeridos para +la aplicación se cargan como módulos independientes, y el middleware `router` +ya no se carga explícitamente en la aplicación. + +También notará que el archivo `app.js` es ahora un Nodo. , en contraste con la aplicación independiente generada por el generador anterior. + +Después de instalar las dependencias, inicie la aplicación usando el siguiente comando: + +```bash +$ npm inicio +``` + +Si miras el script `npm start` en el `paquete. archivo son`, +notarás que el comando real que inicia la aplicación es +`node . bin/www`, que solía ser `node app.js` +en Express 3. + +Porque el archivo `app.js` que fue generado por el generador Express 4 +es ahora un Nodo. s módulo, ya no puede iniciarse independientemente como una aplicación +(a menos que modifiques el código). El módulo debe cargarse en un archivo Node.js +y debe iniciarse a través del archivo Node.js. El archivo Node.js es `./bin/www` +en este caso. + +Ni el directorio `bin` ni el archivo sin extensión `www` +es obligatorio para crear una aplicación Express o iniciar la aplicación. Son +solo sugerencias hechas por el generador, así que siéntete libre de modificarlas para adaptarse a tus +necesidades. + +Para deshacerse del directorio `www` y mantener las cosas de la forma "Express 3", +borrar la línea que dice `module. xports = app;` al final del archivo +`app.js`, luego pega el siguiente código en su lugar: + +```js +app.set('port', process.env.PORT || 3000); + +var server = app.listen(app.get('port'), () => { + debug('Servidor Express escuchando en el puerto ' + server.address().port); +}); +``` + +Asegúrese de cargar el módulo `debug` en la parte superior del archivo `app.js` usando el siguiente código: + +```js +var debug = require('debug')('app4'); +``` + +A continuación, cambia `"start": "node ./bin/www"` en el archivo `package.json` a `"start": "node app.js"`. + +Ahora ha movido la funcionalidad de `./bin/www` de vuelta a +`app.js`. Este cambio no es recomendable, pero el ejercicio te ayuda +a entender cómo el `. bin/www` archivo funciona, y por qué el archivo `app.js` +ya no comienza por sí mismo. diff --git a/src/content/pages/es/guide/migrating-5.mdx b/src/content/pages/es/guide/migrating-5.mdx new file mode 100644 index 0000000000..92e0ff5498 --- /dev/null +++ b/src/content/pages/es/guide/migrating-5.mdx @@ -0,0 +1,678 @@ +--- +title: Moviendo a Express 5 +description: Una guía completa para migrar sus aplicaciones Express.js de la versión 4 a 5, detallando los cambios de ruptura, métodos obsoletos y nuevas mejoras. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express 5 no es muy diferente de Express 4; aunque mantiene la misma API básica, todavía hay cambios que rompen la compatibilidad con la versión anterior. Por lo tanto, una aplicación construida con Express 4 podría no funcionar si la actualiza para usar Express 5. + +Para instalar esta versión, necesita tener una versión 18 o superior de Node.js. Luego, ejecuta el siguiente comando en el directorio de tu aplicación: + +```sh +npm instalar "express@5" +``` + +Luego puede ejecutar sus pruebas automatizadas para ver qué falla, y arreglar problemas de acuerdo a las actualizaciones que se listan a continuación. Después de gestionar los fallos de prueba, ejecuta tu aplicación para ver qué errores ocurren. Descubrirá de inmediato si la aplicación utiliza cualquier método o propiedades que no sean compatibles. + +## Códigos Express 5 + +Para ayudarle a migrar su servidor exprés, hemos creado un conjunto de códigos que te ayudarán a actualizar automáticamente tu código a la última versión de Express. + +Ejecutar el siguiente comando para ejecutar todos los codemods disponibles: + +```sh +codemod@latest @expressjs/v5-migration-recipe +``` + +Si quieres ejecutar un código específico, puedes ejecutar el siguiente comando: + +```sh +codemod@latest @expressjs/nombre-codemod npx +``` + +Puedes encontrar la lista de códigos disponibles [here](https://codemod.link/express). + +## Cambios en Express 5 + +**Métodos y propiedades eliminadas** + + + +**Cambiado** + + + +**Mejoras** + + + +## Métodos y propiedades eliminados + +Si utiliza cualquiera de estos métodos o propiedades en su aplicación, se bloqueará. Por lo tanto, necesitarás cambiar tu aplicación después de actualizar a la versión 5. + +### app.del() + +Express 5 ya no soporta la función `app.del()`. Si utiliza esta función, se arroja un error. Para registrar rutas HTTP DELETE, utilice la función `app.delete()` en su lugar. + +Inicialmente, `del` fue usado en lugar de `delete`, porque `delete` es una palabra clave reservada en JavaScript. Sin embargo, a partir de ECMAScript 6, `delete` y otras palabras clave reservadas pueden utilizarse legalmente como nombres de propiedad. + + +Puedes reemplazar las firmas obsoletas con el siguiente comando: + +```plaintext +codemod@latest @expressjs/route-del-de-borrar npx +``` + + + +```js +// v4 +app.del('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); + +// v5 +app. elete('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); +``` + +### app.param(fn) + +La firma `app.param(fn)` fue usada para modificar el comportamiento de la función `app.param(name, fn)`. Ha sido obsoleto desde v4.11.0, y Express 5 ya no lo soporta en absoluto. + +### Nombres de métodos pluralizados + +Los siguientes nombres de métodos han sido pluralizados. En Express 4, el uso de los métodos antiguos resultó en una advertencia de desaprobación. Express 5 ya no los soporta: + +`req.acceptsCharset()` es reemplazado por `req.acceptsCharsets()`. + +`req.acceptsEncoding()` es reemplazado por `req.acceptsEncodings()`. + +`req.acceptsLanguage()` es reemplazado por `req.acceptsLanguages()`. + + +Puedes reemplazar las firmas obsoletas con el siguiente comando: + +```plaintext +npx codemod@latest @expressjs/pluralize-nombre-método- +``` + + + +```js +// v4 +app.all('/', (req, res) => { + req.acceptsCharset('utf-8'); + req. cceptsEncoding('br'); + req.acceptsLanguage('en'); + + // ... +}); + +// v5 +app. ll('/', (req, res) => { + req.acceptsCharsets('utf-8'); + req.acceptsEncodings('br'); + req.acceptsLanguages('es'); + + // ... +}); +``` + +### Posible coma (:) en el nombre de app.param(nombre, fn) + +Un personaje con dos puntos (:) en el nombre de la aplicación `. aram(name, fn)` función es un remanente de Express 3, y por el bien de la compatibilidad hacia atrás, Express 4 lo soportó con un aviso de desaprobación. Express 5 lo ignorará silenciosamente y usará el parámetro de nombre sin prefijarlo con dos puntos. + +Esto no debería afectar tu código si sigues la documentación Express 4 de [app.param](/en/4x/api#app.param), ya que no hace mención alguna de los dos puntos principales. + +### req.param(nombre) + +Se ha eliminado este método potencialmente confuso y peligroso de recuperar datos de formularios. Ahora necesitará buscar específicamente el nombre del parámetro enviado en el objeto `req.params`, `req.body`, o `req.query`. + + +Puedes reemplazar las firmas obsoletas con el siguiente comando: + +```plaintext +codemod@latest @expressjs/explícit-request-params npx +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + const id = req.param('id'); + const body = req. aram('body'); + const query = req.param('query'); + + // ... +}); + +// v5 +app.post('/user', (req, res) => { + const id = req.params. d; + const body = req.body; + const query = req.query; + + // ... +}); +``` + +### res.json(obj, estado) + +Express 5 ya no soporta la firma `res.json(obj, status)`. En su lugar, establece el estado y luego lo encadena al método `res.json()` de esta manera: `res.status(status).json(obj)`. + + +Puedes reemplazar las firmas obsoletas con el siguiente comando: + +```plaintext +npx codemod@latest @expressjs/status-end +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.json({ name: 'Ruben' }, 201); +}); + +// v5 +app. ost('/user', (req, res) => { + res.status(201).json({ name: 'Ruben' }); +}); +``` + +### res.jsonp(obj, status) + +Express 5 ya no soporta la firma `res.jsonp(obj, status)`. En su lugar, establece el estado y luego lo encadena al método `res.jsonp()` de esta manera: `res.status(status).jsonp(obj)`. + + +Puedes reemplazar las firmas obsoletas con el siguiente comando: + +```plaintext +npx codemod@latest @expressjs/status-end +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.jsonp({ name: 'Ruben' }, 201); +}); + +// v5 +app. ost('/user', (req, res) => { + res.status(201).jsonp({ name: 'Ruben' }); +}); +``` + +### res.redirect(url, status) + +Express 5 ya no soporta la firma `res.redirect(url, status)`. En su lugar, utilice la siguiente firma: `res.redirect(status, url)`. + + +Puedes reemplazar las firmas obsoletas con el siguiente comando: + +```plaintext +codemod@latest @expressjs/redirect-arg-order npx +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('/users', 301); +}); + +// v5 +app. et('/user', (req, res) => { + res.redirect(301, '/users'); +}); +``` + +### res.redirect('back') y res.location('back') + +Express 5 ya no soporta la cadena mágica `back` en los métodos `res.redirect()` y `res.location()`. En su lugar, utilice el valor `req.get('Referrer') || '/'` para redirigir de vuelta a la página anterior. En Express 4, los métodos `res.redirect('back')` y `res.location('back')` fueron obsoletos. + + +Puedes reemplazar las firmas obsoletas con el siguiente comando: + +```plaintext +codemod@latest @expressjs/back-redirect-deprecated +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('back'); +}); + +// v5 +app. et('/user', (req, res) => { + res.redirect(req.get('Referrer') || '/'); +}); +``` + +### res.send(cuerpo, estado) + +Express 5 ya no soporta la firma `res.send(obj, status)`. En su lugar, establece el estado y luego lo encadena al método `res.send()` de esta manera: `res.status(status).send(obj)`. + + +Puedes reemplazar las firmas obsoletas con el siguiente comando: + +```plaintext +npx codemod@latest @expressjs/status-end +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send({ name: 'Ruben' }, 200); +}); + +// v5 +app. et('/user', (req, res) => { + res.status(200).send({ name: 'Ruben' }); +}); +``` + +### res.send(status) + +Express 5 ya no soporta la firma `res.send(status)`, donde `status` es un número. En su lugar, use el `res. función endStatus(statusCode)`, que establece el código de estado de la cabecera de respuesta HTTP y envía la versión de texto del código: "No encontrado", "Error interno del servidor", y así sucesivamente. +Si necesita enviar un número usando el `res. función end()`, cita el número para convertirlo en una cadena, para que Express no lo interprete como un intento de usar la antigua firma no soportada. + + +Puedes reemplazar las firmas obsoletas con el siguiente comando: + +```plaintext +npx codemod@latest @expressjs/status-end +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send(200); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendStatus(200); +}); +``` + +### res.sendfile() + +La función `res.sendfile()` ha sido reemplazada por una versión `res.sendFile()` con casilla de camellos en Express 5. + +**Nota:** En Express 5, `res. endFile()` utiliza el paquete `mime-types` para la detección de tipos MIME, que devuelve diferentes valores de Tipo de Contenido que Express 4 para varios tipos de archivo comunes: + +* Archivos JavaScript (.js): ahora "text/javascript" en lugar de "application/javascript" +* Archivos JSON (.json): ahora "application/json" en lugar de "text/json" +* Archivos CSS (.css): ahora "text/css" en lugar de "text/plain" +* Archivos XML (.xml): ahora "application/xml" en lugar de "text/xml" +* Archivos de fuente (.woff): ahora "font/woff" en lugar de "application/font-woff" +* Archivos SVG (.svg): ahora "image/svg+xml" en lugar de "application/svg+xml" + + +Puedes reemplazar las firmas obsoletas con el siguiente comando: + +```plaintext +codemod@latest @expressjs/camelcase-sendfile npx +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.sendfile('/path/to/file'); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendFile('/path/to/file'); +}); +``` + +### router.param(fn) + +La firma `router.param(fn)` fue usada para modificar el comportamiento de la función `router.param(name, fn)`. Ha sido obsoleto desde v4.11.0, y Express 5 ya no lo soporta en absoluto. + +### express.static.mime + +En Express 5, `mime` ya no es una propiedad exportada del campo `static`. +Usa el [`mime-types` paquete](https://github.com/jshttp/mime-types) para trabajar con valores de tipo MIME. + +**Importante:** Este cambio afecta no sólo al uso directo de `express.static.mime` sino también a otros métodos Express que dependen de la detección de tipo MIME, como `res.sendFile()`. Los siguientes tipos MIME han cambiado de Express 4: + +* Archivos JavaScript (.js): ahora servido como "text/javascript" en lugar de "application/javascript" +* Archivos JSON (.json): ahora servido como "application/json" en lugar de "text/json" +* Archivos CSS (.css): ahora servido como "text/css" en lugar de "text/plain" +* Archivos HTML (): ahora servido como "text/html; charset=utf-8" en lugar de sólo "text/html" +* Archivos XML (.xml): ahora servido como "application/xml" en lugar de "text/xml" +* Archivos de fuente (.woff): ahora servido como "font/woff" en lugar de "application/font-woff" + +```js +// v4 +express.static.mime.lookup('json'); + +// v5 +const mime = require('mime-types'); +mime.lookup('json'); +``` + +### express:router debug logs + +En Express 5, la lógica de manejo del router es realizada por una dependencia. Por lo tanto, los registros de depuración +para el enrutador ya no están disponibles bajo el espacio de nombres `express:`. +En v4, los registros estaban disponibles bajo los espacios de nombres `express:router`, `express:router:layer`, +y `express:router`. Todos estos fueron incluidos bajo el espacio de nombres `express:*`. +En v5.1+, los registros están disponibles bajo los espacios de nombres `router`, `router:layer`, y `router:route`. +Los registros de `router:layer` y `router:route` están incluidos en el namespace `router:*`. +Para lograr el mismo detalle del registro de depuración al usar `express:*` en v4, usa una conjunción de +`express:*`, `router`, y `router:*`. + +```sh + +DEBUG=expresar:* node index.js + + +DEBUG=expresar:*,router,router:* node index.js +``` + +## Cambiado + +### Ruta de ruta que coincide con sintaxis + +Ruta de ruta que coincide con la sintaxis es cuando se proporciona una cadena como el primer parámetro a las APIs `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, y `router.use()`. Se han realizado los siguientes cambios en cómo la cadena de ruta se corresponde con una solicitud entrante: + +* El comodín `*` debe tener un nombre, coincidiendo con el comportamiento de los parámetros `:`, use `/*splat` en lugar de `/*` + +```js +// v4 +app.get('/*', async (req, res) => { + res.send('ok'); +}); + +// v5 +app. et('/*splat', async (req, res) => { + res.send('ok'); +}); +``` + + +`*splat` coincide con cualquier ruta sin la ruta raíz. Si necesita coincidir con la ruta de la raíz también `/`, puede usar `/{*splat}`, envolviendo el comodín entre llaves. + +```js +// v5 +app.get('/{*splat}', async (req, res) => { + res.send('ok'); +}); +``` + + + +* El carácter opcional `?` ya no es compatible, utilice llaves en su lugar. + +```js +// v4 +app.get('/:file.:ext?', async (req, res) => { + res.send('ok'); +}); + +// v5 +app. et('/:file{.:ext}', async (req, res) => { + res.send('ok'); +}); +``` + +* Los caracteres de expresión regular no son compatibles. Por ejemplo: + +```js +app.get('/[discussion|page]/:slug', async (req, res) => { + res.status(200).send('ok'); +}); +``` + +debe cambiarse a: + +```js +app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { + res.status(200).send('ok'); +}); +``` + +* Algunos caracteres han sido reservados para evitar confusión durante la actualización (`()[]?+!`), use `\` para escapar de ellos. +* Los nombres de parámetros ahora soportan identificadores JavaScript válidos, o citan como `:"this"`. + +### Las promesas rechazadas manejadas por middleware y manejadores + +Solicitar middleware y manejadores que devuelven promesas rechazadas ahora son manejados reenviando el valor rechazado como un `Error` al middleware que maneja errores. Esto significa que usar 'async' funciones como middleware y manejadores son más fáciles que nunca. Cuando se arroja un error en una función `async` o una promesa rechazada es `await`ed dentro de una función asíncrona, esos errores se pasarán al gestor de errores como si llamara a `next(err)`. + +Detalles de cómo Express maneja los errores se cubren en la [documentación de manejo de errores](/en/guide/error-handling). + +### express.urlencoded + +El método `express.urlencoded` hace que la opción `extended` sea `false` por defecto. + +### express.static dotfiles + +En Express 5, la opción `dotfiles` de `express.static` ahora es `ignore"`. Este es un cambio de Express 4, donde los ficheros de puntos fueron servidos por defecto. Como resultado, archivos dentro de un directorio que comienza con un punto (`.`), como `. ell-known`, ya no será accesible y devolverá un error **404 No encontrado**. Esto puede romper la funcionalidad que depende de servir directorios de puntos, como Android App Links y Apple Universal Links. + +Ejemplo de código de ruptura: + +```js +// v4 +app.use(express.static('public')); +``` + +Después de migrar a Express 5, una solicitud a `/.well-known/assetlinks.json` resultará en un **404 No Encontrado**. + +Para arreglar esto, sirve directorios de puntos específicos explícitamente usando \`dotfiles: opción "allow"": + +```js +// v5 +app.use('/.well-known', express.static('public/.well-known', { dotfiles: 'allow' })); +app.use(express.static('public')); +``` + +Este enfoque le permite servir de forma segura sólo los directorios de puntos deseados mientras mantiene el comportamiento seguro por defecto para otros archivos de puntos, que permanecen inaccesibles. + +### app.listen + +En Express 5, el método `app.listen` invocará la función callback proporcionada por el usuario (si se proporciona) cuando el servidor reciba un evento de error. En Express 4, esos errores se lanzarían. This change shifts error handling responsibility to the callback function in Express 5. Si hay un error, se pasará al callback como argumento. +Por ejemplo: + +```js +const server = app.listen(8080, '0.0.0.0', (error) => { + if (error) { + throw error; // e.g. EADDRINUSE + } + console.log(`Escuchando en ${JSON.stringify(server.address())}`); +}); +``` + +### app.router + +El objeto `app.router`, que fue eliminado en Express 4, ha regresado en Express 5. En la nueva versión, este objeto es sólo una referencia al router base Express, a diferencia de en Express 3, donde una aplicación tuvo que cargarla explícitamente. + +### req.body + +La propiedad `req.body` devuelve `undefined` cuando el cuerpo no ha sido analizado. En Express 4, devuelve `{}` por defecto. + +### req.host + +En Express 4, la función `req.host` borró incorrectamente del número de puerto si estaba presente. En Express 5, el número de puerto se mantiene. + +### req.params + +El objeto `req.params` ahora tiene un **prototipo nulo** al usar rutas de cadenas. Sin embargo, si la ruta se define con una expresión regular, `req.params` sigue siendo un objeto estándar con un prototipo normal. Además, hay dos cambios de comportamiento importantes: + +**Los parámetros comodín ahora son arrays:** + +Los comodines (por ejemplo, `/*splat`) capturan segmentos de ruta como una matriz en lugar de una sola cadena. + +```js +app.get('/*splat', (req, res) => { + // GET /foo/bar + console.dir(req. arams); + // => [Object: null prototype] { splat: [ 'foo', 'bar' ] } +}); +``` + +**Parámetros no coincidentes son omitidos:** + +En Express 4, los comodines no coinciden eran cadenas vacías (`''`) y los parámetros opcionales `:` (usando `?`) tenían una clave con valor `undefined`. En Express 5, los parámetros no coincidentes se omiten completamente de `req.params`. + +```js +// v4: unmatched wildcard is empty string +app.get('/*', (req, res) => { + // GET / + console.dir(req. arams); + // => { '0': '' } +}); + +// v4: unmatched optional param is undefined +app. et('/:file.:ext?', (req, res) => { + // GET /image + console. ir(req.params); + // => { file: 'image', ext: undefined } +}); + +// v5: unmatched optional param is omitted +app.get('/:file{. ext}', (req, res) => { + // GET /image + console.dir(req. arams); + // => [Object: null prototype] { file: 'image' } +}); +``` + +### req.query + +La propiedad `req.query` ya no es una propiedad escribible y en su lugar es un getter. El analizador de consultas por defecto ha sido cambiado de "extendido" a "simple". + +### res.clearCookie + +El método `res.clearCookie` ignora las opciones `maxAge` y `expires` proporcionadas por el usuario. + +### res.estado + +El método `res.status` sólo acepta enteros en el rango de `100` a `999`, siguiendo el comportamiento definido por Node. , y devuelve un error cuando el código de estado no es un entero. + +### res.variar + +El `res.vary` arroja un error cuando falta el argumento `field`. En Express 4, si el argumento fue omitido, dio una advertencia en la consola + +## Mejoras + +### res.render() + +Este método ahora fuerza el comportamiento asíncrono para todos los motores de vista, evitando errores causados por motores de vista que tenían una implementación sincrónica y que violaban la interfaz recomendada. + +### Soporte de codificación Brotli + +Express 5 soporta la codificación de Brotli para peticiones recibidas de clientes que lo soportan. diff --git a/src/content/pages/es/resources/glossary.mdx b/src/content/pages/es/resources/glossary.mdx new file mode 100644 index 0000000000..18acaa588f --- /dev/null +++ b/src/content/pages/es/resources/glossary.mdx @@ -0,0 +1,61 @@ +--- +title: Glossary +description: Un glosario completo de términos relacionados con Express.js, Node.js, middleware, rutaje y otros conceptos clave para ayudarle a entender y usar Express efectivamente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +### aplicación + +En general, uno o más programas diseñados para llevar a cabo operaciones con un propósito específico. En el contexto de Express, un programa que utiliza la API Express corriendo en la plataforma Node.js. También podría referirse a un [objeto de aplicación](/en/api#express). + +### API + +Interfaz de programación de aplicaciones. Escribe la abreviatura cuando se utiliza por primera vez. + +### Exprés + +Un marco web rápido, sin opinión y minimalista para aplicaciones Node.js. En general, se prefiere "Express" a "Express.js", aunque esta última es aceptable. + +### libuv + +Una biblioteca de soporte multiplataforma que se centra en E/S asíncrona, desarrollada principalmente para su uso por Node.js. + +### middleware + +Una función que es invocada por la capa de enrutamiento Express antes del gestor de solicitud final, y por lo tanto se encuentra en el medio entre una solicitud cruda y la ruta final deseada. Unos pocos puntos finos de terminología en torno a middleware: + +* `var foo = require('middleware')` es llamado *requiring* o *using* un módulo Node.js. Luego la instrucción `var mw = foo()` típicamente devuelve el middleware. +* `app.use(mw)` se llama *agregando el middleware a la pila global de procesamiento de datos*. +* `app.get('/foo', mw, function (req, res) { ... })` se llama *adding the middleware to the "GET /foo" processing stack*. + +### Node.js + +Una plataforma de software que se utiliza para construir aplicaciones de red escalables. Node.js utiliza JavaScript como su lenguaje de scripting y logra un alto rendimiento a través de E/S sin bloqueo y un bucle de eventos con un solo hilo. Ver [nodejs.org](https://nodejs.org/en/). **Nota de uso**: Inicialmente, "Node.js", a partir de entonces "Node". + +### código abierto, código abierto + +Cuando se utiliza como adjetivo, guión; por ejemplo: "Esto es software de código abierto". Ver [Software de código abierto en Wikipedia](http://en.wikipedia.org/wiki/Open-source_software). + + + +Aunque es común no guiar este término, estamos utilizando las reglas estándar de Inglés para +gueando un adjetivo compuesto. + + + +### solicitud + +Una petición HTTP. Un cliente envía un mensaje de petición HTTP a un servidor, el cual devuelve una respuesta. La solicitud debe utilizar uno de varios [métodos de petición](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) como GET, POST, y así sucesivamente. + +### respuesta + +Una respuesta HTTP. Un servidor devuelve un mensaje de respuesta HTTP al cliente. La respuesta contiene información sobre el estado de finalización de la solicitud y también podría contener el contenido solicitado en su cuerpo del mensaje. + +### ruta + +Parte de una URL que identifica un recurso. Por ejemplo, en `http://foo.com/products/id`, "/products/id" es la ruta. + +### enrutador + +Ver [router](/en/api#router) en la referencia API. diff --git a/src/content/pages/es/resources/utils.md b/src/content/pages/es/resources/utils.md new file mode 100644 index 0000000000..a644860fee --- /dev/null +++ b/src/content/pages/es/resources/utils.md @@ -0,0 +1,22 @@ +--- +title: utilidades exprés +description: Descubra los módulos de utilidad relacionados con Express.js y Node.js, incluyendo herramientas para cookies, protección CSRF, análisis de URL, enrutamiento, y más para mejorar sus aplicaciones. +--- + +## Funciones de utilidad Express + +La organización [pillarjs](https://github.com/pillarjs) de GitHub contiene varios módulos +para funciones de utilidad que pueden ser generalmente útiles. + +| Módulos de utilidad | Descripción | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [cookies](https://www.npmjs.com/package/cookies) | Obtener y configurar cookies HTTP(S) que se pueden firmar para evitar manipulaciones, usando Keygrip. Se puede usar con la librería HTTP de Node.js o como middleware Express. | +| [csrf](https://www.npmjs.com/package/csrf) | Contiene la lógica detrás de la creación y verificación de token CSRF. Utilice este módulo para crear un middleware CSRF personalizado. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Función para invocar como paso final para responder a la petición HTTP. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Analizar una URL con caché. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Convierte una cadena de ruta tipo Express-style como \`\`/user/:name\` en una expresión regular. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Resuelve una ruta relativa contra una ruta raíz con validación. | +| [router](https://www.npmjs.com/package/router) | Enrutador simple de tipo middleware. | +| [send](https://www.npmjs.com/package/send) | Biblioteca para streaming de archivos como respuesta HTTP, con soporte para respuestas parciales (rangos), negociación condicional-GET y eventos granulares. | + +Para módulos adicionales relacionados con HTTP, consulte [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/es/support.md b/src/content/pages/es/support.md new file mode 100644 index 0000000000..d70f83842d --- /dev/null +++ b/src/content/pages/es/support.md @@ -0,0 +1,23 @@ +--- +title: Soporte para versiones +description: Encuentre información sobre el programa de soporte para diferentes versiones de Express.js, incluyendo las versiones que se mantienen actualmente y las políticas de fin de su vida. +--- + +Sólo se admite la última versión de cualquier línea de lanzamiento mayor. + +Las versiones que son EOL (end-of-life) _pueden_ recibir actualizaciones para vulnerabilidades de seguridad críticas, pero el equipo de Express no ofrece ninguna garantía y no planea abordar o corregir versiones para ningún problema encontrado. + +| Versión principal | Versión mínima de Node.js | Inicio de Soporte | Fecha de fin de soporte | +| ------------------------------------------- | ----------------------------------------- | ------------------ | ----------------------- | +| [**v5.x**](/en/5x/api) | 18 | Septiembre de 2024 | **en curso** | +| [**v4.x**](/en/4x/api) | 0.10.0 | Abril de 2014 | **en curso** | +| [**v3.x**](/en/3x/api) | 0.8.0 | Octubre de 2012 | Julio de 2015 | +| [**v2.x**](/2x/) | 0.4.1 | Marzo de 2011 | Julio de 2012 | +| **v1.x** | 0.2.0 | Diciembre 2010 | Marzo de 2011 | +| **v0.14.x** | 0.1.98 | Diciembre 2010 | Diciembre 2010 | + +## Opciones de soporte comercial + +Si no puede actualizar a una versión soportada de Express, póngase en contacto con uno de nuestros socios para recibir actualizaciones de seguridad: + +- [Soporte de HeroDevs finalizado](http://www.herodevs.com/support/express-nes?utm_source=expressjs&utm_medium=link&utm_campaign=express_eol_page) diff --git a/src/content/pages/fr/advanced/best-practice-performance.md b/src/content/pages/fr/advanced/best-practice-performance.md new file mode 100644 index 0000000000..65b26fdabe --- /dev/null +++ b/src/content/pages/fr/advanced/best-practice-performance.md @@ -0,0 +1,305 @@ +--- +title: 'Meilleures pratiques de production : performance et fiabilité' +description: Découvrez les meilleures pratiques de performance et de fiabilité pour les applications Express en production, couvrant les optimisations de code et les configurations d'environnement pour des performances optimales. +--- + +Cet article traite des meilleures pratiques de performance et de fiabilité pour les applications Express déployées en production. + +Ce sujet tombe clairement dans le monde des « dévalises », englobant tant le développement traditionnel que les opérations. En conséquence, l'information est divisée en deux parties : + +- Les choses à faire dans votre code (la partie développeur) : + - [Utiliser la compression gzip](#use-gzip-compression) + - [Ne pas utiliser de fonctions synchrones](#dont-use-synchronous-functions) + - [Faire la journalisation correctement](#do-logging-correctly) + - [Gérer les exceptions correctement] (#handle-exceptions-properly) +- Choses à faire dans votre environnement / configuration (partie Ops) : + - [Définir NODE_ENV comme "production"](#set-node_env-to-production) + - (#ensure-your-app-automatically-restarts) + - [Exécuter votre application dans un cluster](#run-your-app-in-a-cluster) + - (#cache-request-results) + - [Utiliser un répartiteur de charge](#use-a-load-balancer) + - [Utiliser un proxy inverse](#use-a-reverse-proxy) + +## Les choses à faire dans votre code + +Voici quelques choses que vous pouvez faire dans votre code pour améliorer les performances de votre application : + +- [Utiliser la compression gzip](#use-gzip-compression) +- [Ne pas utiliser de fonctions synchrones](#dont-use-synchronous-functions) +- [Faire la journalisation correctement](#do-logging-correctly) +- [Gérer les exceptions correctement] (#handle-exceptions-properly) + +### Utiliser la compression gzip + +La compression Gzip peut réduire considérablement la taille du corps de réponse et ainsi augmenter la vitesse d'une application web. Utilisez le middleware [compression](https://www.npmjs.com/package/compression) pour la compression gzip dans votre application Express. Par exemple : + +```js +const compression = require('compression'); +const express = require('express'); +const app = express(); + +app.use(compression()); +``` + +Pour un site internet à fort trafic en production, la meilleure façon de mettre en place une compression est de l'implémenter à un niveau de proxy inverse (voir [Utiliser un proxy inverse](#use-a-reverse-proxy)). Dans ce cas, vous n'avez pas besoin d'utiliser le middleware de compression. Pour plus de détails sur l'activation de la compression gzip dans Nginx, voir [Module ngx_http_gzip_module](http://nginx.org/en/docs/http/ngx_http_gzip_module) dans la documentation Nginx. + +### Ne pas utiliser les fonctions synchrones + +Les fonctions et méthodes synchrones lient le processus d'exécution jusqu'à ce qu'elles soient retournées. Un seul appel à une fonction synchrone peut retourner en quelques microsecondes ou millisecondes, Cependant, dans les sites Web à fort trafic, ces appels s'ajoutent et réduisent les performances de l'application. Évitez leur utilisation en production. + +Bien que Node et de nombreux modules fournissent des versions synchrones et asynchrones de leurs fonctions, utilisez toujours la version asynchrone en production. Le seul moment où une fonction synchrone peut être justifiée est au démarrage initial. + +Vous pouvez utiliser le flag en ligne de commande `--trace-sync-io` pour afficher une alerte et une trace de pile chaque fois que votre application utilise une API synchrone. Bien sûr, vous ne voudriez pas utiliser cela en production, mais plutôt vous assurer que votre code est prêt pour la production. Voir la [documentation des options de la ligne de commande node](https://nodejs.org/api/cli#cli_trace_sync_io) pour plus d'informations. + +### Faire la journalisation correctement + +En général, il y a deux raisons de se connecter depuis votre application : pour le débogage et pour l'activité des applications de journalisation (essentiellement tout le reste). Utiliser `console.log()` ou `console.error()` pour imprimer les messages de log vers le terminal est pratique courante dans le développement. Mais [ces fonctions sont synchronisées] (https://nodejs.org/api/console#console) lorsque la destination est un terminal ou un fichier, elles ne sont donc pas adaptées à la production, à moins que vous ne conduisiez la sortie vers un autre programme. + +#### Pour le débogage + +Si vous êtes connecté à des fins de débogage, alors au lieu d'utiliser `console.log()`, utilisez un module de débogage spécial comme [debug](https://www.npmjs.com/package/debug). Ce module vous permet d'utiliser la variable d'environnement DEBUG pour contrôler quels messages de débogage sont envoyés à `console.error()`, le cas échéant. Pour garder votre application purement asynchrone, vous vouliez toujours canaliser `console.error()` vers un autre programme. Mais alors, vous n'allez pas vraiment déboguer en production, n'est-ce pas? + +#### Pour l'activité de l'application + +Si vous connectez l'activité de l'application (par exemple, suivre le trafic ou les appels API), au lieu d'utiliser la « console ». og()\`, utilise une bibliothèque de log comme [Pino](https://www.npmjs.com/package/pino), qui est l'option la plus rapide et la plus efficace disponible. + +### Gérer correctement les exceptions + +Les applications de nœud plantent lorsqu'elles rencontrent une exception non prise. Ne pas gérer les exceptions et prendre les actions appropriées fera planter votre application Express et se déconnectera. Si vous suivez les conseils de [Assurez-vous que votre application redémarre automatiquement] (#ensure-your-app-automatically-restarts) ci-dessous, votre application se remettra d'un crash. Heureusement, les applications Express ont généralement un temps de démarrage court. Néanmoins, vous voulez éviter de planter en premier lieu, et pour ce faire, vous devez gérer les exceptions correctement. + +Pour vous assurer de gérer toutes les exceptions, utilisez les techniques suivantes : + +- [Utiliser try-catch](#use-try-catch) +- [Utiliser des promesses](#use-promises) + +Avant de plonger dans ces sujets, vous devriez avoir une compréhension de base de la gestion des erreurs Node/Express : utiliser les premiers callbacks d'erreurs et propager les erreurs dans les middleware. Le noeud utilise une convention "error-first callback" pour retourner des erreurs à partir de fonctions asynchrones, où le premier paramètre de la fonction callback est l'objet erreur, suivi par les données de résultat dans les paramètres successifs. Pour indiquer aucune erreur, passez null comme premier paramètre. La fonction callback doit suivre la première convention de callback pour gérer l'erreur de manière significative. Et dans Express, la meilleure pratique est d'utiliser la fonction next() pour propager les erreurs à travers la chaîne du middleware. + +Pour en savoir plus sur les fondamentaux de la gestion des erreurs, voir : + +- [Gestion des erreurs dans Node.js](https://www.tritondatacenter.com/node-js/production/design/errors) + +#### Utiliser try-catch + +Try-catch est un langage JavaScript que vous pouvez utiliser pour attraper des exceptions dans le code synchrone. Utilisez try-catch, par exemple, pour gérer les erreurs d'analyse JSON comme indiqué ci-dessous. + +Voici un exemple d'utilisation de try-catch pour gérer une éventuelle exception plantant le processus. +Cette fonction du middleware accepte un paramètre de champ de requête nommé "params" qui est un objet JSON. + +```js +app.get('/search', (req, res) => { + // Simulating async operation + setImmediate(() => { + const jsonStr = req.query.params; + try { + const jsonObj = JSON.parse(jsonStr); + res.send('Success'); + } catch (e) { + res.status(400).send('Invalid JSON string'); + } + }); +}); +``` + +Cependant, essayer-catch ne fonctionne que pour du code synchrone. Parce que la plate-forme Node est principalement asynchrone (particulièrement dans un environnement de production), les captures d'essai ne prendront pas beaucoup d'exceptions. + +#### Utiliser les promesses + +Lorsqu'une erreur est levée dans une fonction `async` ou qu'une promesse rejetée est attendue à l'intérieur d'une fonction `async`, ces erreurs seront passées au gestionnaire d'erreurs comme si elle appelait `next(err)` + +```js +app.get('/', async (req, res, next) => { + const data = await userData(); // If this promise fails, it will automatically call `next(err)` to handle the error. + + res.send(data); +}); + +app.use((err, req, res, next) => { + res.status(err.status ?? 500).send({ error: err.message }); +}); +``` + +De plus, vous pouvez utiliser des fonctions asynchrones pour votre middleware, et le routeur gérera des erreurs si la promesse échoue, par exemple : + +```js +app.use(async (req, res, next) => { + req.locals.user = await getUser(req); + + next(); // This will be called if the promise does not throw an error. +}); +``` + +La meilleure pratique est de gérer les erreurs le plus près possible du site. Donc, tant que ceci est maintenant géré dans le routeur, Il est préférable d’attraper l’erreur dans le middleware et de la manipuler sans s’appuyer sur un middleware séparé. + +#### Ce qu'il ne faut pas faire + +Une chose que vous ne devriez pas _faire_ est d'écouter l'évènement `uncatghtException` émise lorsqu'une exception bulle tout le retour à la boucle d'événement. Ajouter un event listener pour `uncatghtException` changera le comportement par défaut du processus qui rencontre une exception ; le processus continuera à fonctionner malgré l'exception. Cela peut sembler un bon moyen d'empêcher votre application de planter, mais continuer à exécuter l'application après une exception non capturée est une pratique dangereuse et n'est pas recommandé, parce que l'état du processus devient peu fiable et imprévisible. + +De plus, l'utilisation de `uncaughtException` est officiellement reconnue comme [crude](https://nodejs.org/api/process#process_event_uncaughtexception). Donc l'écoute de `uncatghtException` est juste une mauvaise idée. C'est pourquoi nous recommandons des choses comme des processus multiples et des superviseurs : plantage et redémarrage est souvent le moyen le plus fiable de se remettre d'une erreur. + +Nous ne recommandons pas non plus d'utiliser [domains](https://nodejs.org/api/domain). Il ne résout généralement pas le problème et est un module obsolète. + +## Choses à faire dans votre environnement / configuration + +Voici quelques choses que vous pouvez faire dans votre environnement système pour améliorer les performances de votre application : + +- [Définir NODE_ENV comme "production"](#set-node_env-to-production) +- (#ensure-your-app-automatically-restarts) +- [Exécuter votre application dans un cluster](#run-your-app-in-a-cluster) +- (#cache-request-results) +- [Utiliser un répartiteur de charge](#use-a-load-balancer) +- [Utiliser un proxy inverse](#use-a-reverse-proxy) + +### Définir NODE_ENV à "production" + +La variable d'environnement NODE_ENV spécifie l'environnement dans lequel une application est en cours d'exécution (généralement, développement ou production). L'une des choses les plus simples que vous pouvez faire pour améliorer les performances est de définir NODE_ENV à `production`. + +Définir NODE_ENV sur "production" rend Express: + +- Modèles d'affichage du cache. +- Cache les fichiers CSS générés à partir des extensions CSS. +- Générer des messages d'erreur moins verbeux. + +[Les tests indiquent](https://www.dynatrace.com/news/blog/the-drastic-effects-of-omitting-node-env-in-your-express-js-applications/) que cela peut améliorer les performances de l'application par un facteur de trois ! + +Si vous avez besoin d'écrire du code spécifique à l'environnement, vous pouvez vérifier la valeur de NODE_ENV avec `process.env.NODE_ENV`. Sachez que la vérification de la valeur d'une variable d'environnement entraîne une pénalité de performance, et qu'elle devrait donc être faite avec modération. + +En développement, vous définissez généralement des variables d'environnement dans votre shell interactif, par exemple en utilisant `export` ou votre fichier `.bash_profile`. Mais en général, vous ne devriez pas le faire sur un serveur de production ; au lieu de cela, utilisez le système d'initialisation de votre système d'exploitation (système). La section suivante fournit plus de détails sur l'utilisation de votre système d'initialisation en général, mais le paramètre `NODE_ENV` est si important pour les performances (et facile à faire), qu'il est mis en évidence ici. + +Avec le système, utilisez la directive `Environnement` dans votre fichier unitaire. Par exemple : + +```sh + +Environment=NODE_ENV=production +``` + +Pour plus d'informations, voir [Utilisation des variables d'environnement dans les unités systémiques](https://www.flatcar.org/docs/latest/setup/systemd/environment-variables/). + +### Assurez-vous que votre application redémarre automatiquement + +En production, vous ne voulez pas que votre application soit déconnectée, jamais. Cela signifie que vous devez vous assurer qu'il redémarre à la fois si l'application plante et si le serveur lui-même plante. Bien que vous espériez qu'aucun de ces événements ne se produise, réalistement, vous devez rendre compte des deux éventualités par: + +- Utiliser un gestionnaire de processus pour redémarrer l'application (et Node) quand il plante. +- Utiliser le système d'initialisation fourni par votre système d'exploitation pour redémarrer le gestionnaire de processus lorsque le système d'exploitation plante. Il est également possible d'utiliser le système d'initialisation sans gestionnaire de processus. + +Les applications de nœud plantent si elles rencontrent une exception non prise. La première chose à faire est de s'assurer que votre application est bien testée et gère toutes les exceptions (voir [gérer les exceptions correctement](#handle-exceptions-properly) pour plus de détails). Mais en tant que sécurité pour les échecs, mettez en place un mécanisme pour vous assurer que si et quand votre application se bloque, elle redémarrera automatiquement. + +#### Utiliser un gestionnaire de processus + +En cours de développement, vous avez démarré votre application simplement à partir de la ligne de commande avec `node server.js` ou quelque chose de similaire. Mais faire cela dans la production est une recette de désastre. Si l'application plante, elle sera hors ligne jusqu'à ce que vous la redémarrez. Pour s'assurer que votre application redémarre si elle plante, utilisez un gestionnaire de processus. Un gestionnaire de processus est un "conteneur" pour les applications qui facilitent le déploiement, fournissent une disponibilité élevée et vous permettent de gérer l'application à l'exécution. + +En plus de redémarrer votre application en cas de plantage, un gestionnaire de processus peut vous permettre de : + +- Obtenez un aperçu de la performance de l’exécution et de la consommation des ressources. +- Modifiez les paramètres de façon dynamique pour améliorer les performances. +- Contrôle de la grappe (pm2). + +Historiquement, il était populaire d'utiliser un gestionnaire de processus Node.js comme [PM2](https://github.com/Unitech/pm2). Consultez leur documentation si vous le souhaitez. Cependant, nous vous recommandons d'utiliser votre système d'initialisation pour la gestion des processus. + +#### Utiliser un système d'initialisation + +La prochaine étape de la fiabilité est de s'assurer que votre application redémarre lorsque le serveur redémarre. Les systèmes peuvent encore diminuer pour diverses raisons. Pour vous assurer que votre application redémarre si le serveur plante, utilisez le système d'initialisation intégré à votre système d'exploitation. Le système d'initialisation principal utilisé aujourd'hui est [systemd](https://wiki.debian.org/systemd). + +Il y a deux façons d'utiliser les systèmes d'initialisation avec votre application Express : + +- Exécutez votre application dans un gestionnaire de processus et installez le gestionnaire de processus en tant que service avec le système d'initialisation. Le gestionnaire de processus redémarrera votre application lorsque l'application se bloque, et le système d'initialisation redémarrera le gestionnaire de processus lorsque le système d'exploitation redémarrera. C'est l'approche recommandée. +- Exécutez votre application (et Node) directement avec le système d'initialisation. C'est un peu plus simple, mais vous n'aurez pas les avantages supplémentaires d'utiliser un gestionnaire de processus. + +##### Systemd + +Systemd est un gestionnaire de systèmes et de services Linux. La plupart des grandes distributions Linux ont adopté le système comme système d'initialisation par défaut. + +Un fichier de configuration du service système est appelé un fichier _unit avec un nom de fichier se terminant par `.service`. Voici un exemple de fichier d'unité pour gérer une application Node directement. Remplacez les valeurs placées en `` pour votre système et votre application: + +```sh +[Unit] +Description= + +[Service] +Type=simple +ExecStart=/usr/local/bin/node +WorkingDirectory= + +User=nobody +Group=nogroup + + +Environment=NODE_ENV=production + + +LimitNOFILE=infinity + + +LimitCORE=infinity + +StandardInput=null +StandardOutput=syslog +StandardError=syslog +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +Pour plus d'informations sur le système, voir [systemd reference (man page)] (http://www.freedesktop.org/software/systemd/man/systemd.unit). + +### Exécutez votre application dans un cluster + +Dans un système multi-cœurs, vous pouvez augmenter les performances d'une application Node de plusieurs fois en lançant un cluster de processus. Un cluster exécute plusieurs instances de l'application, idéalement une instance sur chaque noyau de processeur, distribuant ainsi la charge et les tâches entre les instances. + +![Balancing between application instances using the cluster API](/images/clustering.png) + +IMPORTANT: Puisque les instances de l'application s'exécutent sous forme de processus séparés, elles ne partagent pas le même espace mémoire. C'est-à-dire que les objets sont locaux à chaque instance de l'application. Par conséquent, vous ne pouvez pas maintenir l'état dans le code de l'application. Cependant, vous pouvez utiliser un datastore en mémoire comme [Redis](http://redis.io/) pour stocker des données et des états liés à la session. Cette mise en garde s'applique essentiellement à toutes les formes de mise à l'échelle horizontale, qu'il s'agisse de regroupement avec de multiples processus ou de multiples serveurs physiques. + +Dans les applications groupées, les processus de travail peuvent planter individuellement sans affecter le reste des processus. Mis à part les avantages des performances, l'isolement des défaillances est une autre raison de lancer un cluster de processus applicatifs. À chaque fois qu'un processus worker plante, assurez-vous toujours de consigner l'événement et de faire apparaître un nouveau processus en utilisant la fonction cluster.fork(). + +#### Utilisation du module de cluster de Node + +Le groupement est rendu possible avec le [module de clustage] (https://nodejs.org/api/cluster). Cela permet à un processus maître de faire apparaître des processus de travail et de distribuer des connexions entrantes entre les travailleurs. + +#### Utilisation du PM2 + +Si vous déployez votre application avec PM2, alors vous pouvez profiter de la grappe de serveurs _sans_ pour modifier le code de votre application. Vous devez d'abord vous assurer que votre [application est sans états] (https://pm2.keymetrics.io/docs/usage/specifics/#stateless-apps) signifiant qu'aucune donnée locale n'est stockée dans le processus (comme les sessions, les connexions websocket et les autres). + +Lorsque vous exécutez une application avec PM2, vous pouvez activer le **mode de cluster** pour l'exécuter dans une grappe avec un certain nombre d'instances de votre choix, comme le nombre de processeurs disponibles sur la machine. Vous pouvez modifier manuellement le nombre de processus dans le cluster en utilisant l'outil en ligne de commande `pm2` sans arrêter l'application. + +Pour activer le mode cluster, lancez votre application comme suit: + +```bash + +$ pm2 start npm --name my-app -i 4 -- start + +$ pm2 start npm --name my-app -i max -- start +``` + +Ceci peut également être configuré dans un fichier de processus PM2 (`ecosystem.config. s` ou similaire) en définissant `exec_mode` à `cluster` et `instances` au nombre de travaux à commencer. + +Une fois exécutée, l'application peut être mise à l'échelle comme ceci: + +```bash + +$ pm2 scale my-app +3 + +$ pm2 scale my-app 2 +``` + +Pour plus d'informations sur la grappe de serveurs avec PM2, voir [Mode clusters](https://pm2.keymetrics.io/docs/usage/cluster-mode/) dans la documentation PM2. + +### Résultats de la requête de cache + +Une autre stratégie pour améliorer les performances en production est de mettre en cache le résultat des requêtes, afin que votre application ne répète pas l'opération pour répondre à la même requête de manière répétée. + +Utilisez un serveur de cache comme [Varnish](https://www.varnish-cache.org/) ou [Nginx](https://blog.nginx.org/blog/nginx-caching-guide) (voir aussi [Nginx Caching](https://serversforhackers.com/nginx-caching/)) pour améliorer considérablement la vitesse et les performances de votre application. + +### Utiliser un répartiteur de charge + +Quelle que soit l'optimisation d'une application, une seule instance ne peut gérer qu'une quantité limitée de charge et de trafic. Une façon de mettre à l'échelle une application est d'exécuter plusieurs instances et de distribuer le trafic via un répartiteur de charge. La mise en place d'un répartiteur de charge peut améliorer les performances et la vitesse de votre application et l'activer pour augmenter la taille de votre système par une seule instance. + +Un répartiteur de charge est généralement un mandataire inversé qui orchestre le trafic entre et à partir de plusieurs instances et serveurs d'applications. Vous pouvez facilement configurer un répartiteur de charge pour votre application en utilisant [Nginx](https://nginx.org/en/docs/http/load_balancing) ou [HAProxy](https://www.digitalocean.com/community/tutorials/an-introduction-to-haproxy-and-load-balancing-concepts). + +Avec l'équilibrage de charge, vous devrez peut-être vous assurer que les requêtes qui sont associées à un ID de session particulier se connectent au processus qui les a originés. C'est connu sous le nom _affinity_, ou _sticky sessions_, et peut être adressé par la suggestion ci-dessus d'utiliser un stockage de données tel que Redis pour les données de session (selon votre application). Pour une discussion, voir [Utilisation de plusieurs nœuds](https://socket.io/docs/v4/using-multiple-nodes/). + +### Utiliser un proxy inversé + +Un mandataire inversé se trouve devant une application Web et effectue des opérations de support sur les requêtes, en plus de diriger les requêtes vers l'application. Il peut gérer les pages d'erreurs, la compression, la mise en cache, le service de fichiers et l'équilibrage de charge, entre autres. + +Le transfert de tâches qui ne nécessitent pas de connaissance de l'état de l'application à un mandataire inversé libère Express pour effectuer des tâches d'application spécialisées. Pour cette raison, il est recommandé d'exécuter Express derrière un proxy inverse comme [Nginx](https://www.nginx.org/) ou [HAProxy](https://www.haproxy.org/) en production. diff --git a/src/content/pages/fr/advanced/best-practice-security.mdx b/src/content/pages/fr/advanced/best-practice-security.mdx new file mode 100644 index 0000000000..91ef91137b --- /dev/null +++ b/src/content/pages/fr/advanced/best-practice-security.mdx @@ -0,0 +1,276 @@ +--- +title: "Meilleures pratiques de production : Sécurité" +description: Découvrez les meilleures pratiques de sécurité cruciales pour les applications Express en production, y compris l'utilisation de TLS, la validation des entrées, les cookies sécurisés et la prévention des vulnérabilités. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Le terme *"production"* désigne l'étape du cycle de vie du logiciel quand une application ou une API est généralement disponible pour ses utilisateurs finaux ou ses consommateurs. Par contre, dans l'étape *"développement"*, vous êtes toujours en train d'écrire et de tester du code, et l'application n'est pas ouverte à un accès externe. Les environnements système correspondants sont respectivement les environnements *production* et *development*. + +Les environnements de développement et de production sont généralement mis en place différemment et ont des exigences très différentes. Ce qui est bon dans le développement peut ne pas être acceptable dans la production. Par exemple, dans un environnement de développement, vous pouvez vouloir une journalisation détaillée des erreurs pour le débogage, alors que le même comportement peut devenir une préoccupation de sécurité dans un environnement de production. Et en matière de développement, vous n'avez pas à vous soucier de l'évolutivité, de la fiabilité et de la performance, alors que ces préoccupations deviennent cruciales dans la production. + + + +Si vous pensez avoir découvert une faille de sécurité dans Express, veuillez consulter [Politiques et procédures de sécurité +de sécurité [/en/resources/contributing#security-policies-and-procedures). + + + +Les meilleures pratiques de sécurité pour les applications Express en production comprennent: + +* [Meilleures pratiques de production : Sécurité](#production-best-practices-security) + * [Overview](#overview) + * [Ne pas utiliser de versions obsolètes ou vulnérables d'Express] (#dont-use-deprecated-or-vulnerable-versions-of-express) + * [Utiliser TLS](#use-tls) + * [Ne pas faire confiance à la saisie de l'utilisateur](#do-not-trust-user-input) + * [Empêcher les redirections ouvertes](#prevent-open-redirects) + * [Utiliser le casque](#use-helmet) + * [Réduire l'empreinte digitale](#reduce-fingerprinting) + * (#use-cookies-securely) + * [Ne pas utiliser le nom du cookie de session par défaut](#dont-use-the-default-session-cookie-name) + * (#set-cookie-security-options) + * [Empêcher les attaques par force brute contre l'autorisation] (#prevent-brute-force-attacks-against-authorization) + * [Assurez-vous que vos dépendances sont sécurisées](#ensure-your-dependencies-are-secure) + * [Éviter les autres vulnérabilités connues] (#avoid-other-known-vulnerabilities) + * [Considérations supplémentaires](#additional-considerations) + +## Ne pas utiliser les versions obsolètes ou vulnérables de Express + +Express 2.x et 3.x ne sont plus maintenus. Les problèmes de sécurité et de performance dans ces versions ne seront pas résolus. Ne les utilisez pas ! Si vous n'avez pas déménagé vers la version 4, suivez le [guide de migration] (/en/guide/migrating-4) ou envisagez [Options de support commercial] (/en/support#commercial-support-options). + +Assurez-vous également que vous n'utilisez aucune des versions vulnérables Express listées sur la page [Mise à jour de sécurité] (/en/advanced/security-updates). Si vous l'êtes, mettez à jour vers l'une des versions stables, de préférence la plus récente. + +## Utiliser TLS + +Si votre application traite ou transmet des données sensibles, utilisez [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) pour sécuriser la connexion et les données. Cette technologie crypte les données avant qu'elles ne soient envoyées du client au serveur, empêchant ainsi certains hacks courants (et faciles). Bien que les requêtes Ajax et POST puissent ne pas être visiblement évidentes et semblent "cachées" dans les navigateurs, leur trafic réseau est vulnérable à [sniffing de paquets] (https://en.wikipedia.org/wiki/Packet_analyzer) et aux [attaques de l'homme au milieu] (https://en.wikipedia.org/wiki/Man-in-the-middle_attack). + +Il se peut que vous soyez familier avec le cryptage Secure Socket Layer (SSL) . [TLS est simplement la prochaine progression de SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). En d'autres termes, si vous utilisiez SSL auparavant, envisagez la mise à niveau vers TLS. En général, nous recommandons à Nginx de gérer les TLS. Pour une bonne référence pour configurer TLS sur Nginx (et d'autres serveurs), voir [Configurations de serveur recommandées (Mozilla Wiki)] (https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). + +De plus, un outil pratique pour obtenir un certificat TLS gratuit est [Let's Encrypt](https://letsencrypt.org/about/), un outil gratuit, automatisé, et l'autorité de certification ouverte (CA) fournie par le [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). + +## Ne pas faire confiance à la saisie de l'utilisateur + +Pour les applications Web, l'une des exigences de sécurité les plus importantes est la validation et la gestion des entrées des utilisateurs. Cela se présente sous de nombreuses formes et nous ne les couvrirons pas tous. +En fin de compte, la responsabilité de valider et de gérer correctement les types de saisie que votre application accepte est la vôtre. + +### Empêcher les redirections ouvertes + +Un exemple de saisie potentiellement dangereuse de l'utilisateur est une redirection _ouverte, où une application accepte une URL comme entrée utilisateur (souvent dans la requête URL, par exemple `? rl=https://exemple. ) et utilise `res.redirect`pour définir l'en-tête`location\` et +retourne un statut 3xx. + +Une application doit valider qu'elle prend en charge la redirection vers l'URL entrante pour éviter d'envoyer des utilisateurs à des liens malveillants tels que des sites Web d'hameçonnage, entre autres risques. + +Voici un exemple de vérification des URLs avant d'utiliser `res.redirect` ou `res.location`: + +```js +app.use((req, res) => { + essayer { + if (new Url(req. uery.url).host !== 'exemple.com') { + return res.status(400). nd(`Redirection non prise en charge vers l'hôte : ${req.query.url}`); + } + } attraper (e) { + retourne. tatus(400).end(`URL invalide : ${req.query.url}`); + } + res.redirect(req.query.url); +}); +``` + +## Utiliser le Casque + +[Helmet][helmet] peut aider à protéger votre application contre certaines vulnérabilités Web bien connues en définissant correctement les en-têtes HTTP. + +Helmet est une fonction middleware qui définit les en-têtes de réponse HTTP liés à la sécurité. Le casque définit par défaut les en-têtes suivants : + +* `Content-Security-Policy` : Une puissante liste de ce qui peut se passer sur votre page qui atténue de nombreuses attaques +* `Cross-Origin-Opener-Policy`: Aide à isoler votre page +* `Cross-Origin-Resource-Policy`: empêche les autres de charger vos ressources cross-origin +* `Origin-Agent-Cluster`: Modifie l'isolement du processus pour qu'il soit basé sur l'origine +* `Referrer-Policy`: contrôle l'en-tête [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) +* `Strict-Transport-Security` : dit aux navigateurs de préférer HTTPS +* `X-Content-Type-Options`: évite [sniffing MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +* `X-DNS-Prefetch-Control`: contrôle le préchargement DNS +* `X-Download-Options`: force les téléchargements à être sauvegardés (Internet Explorer uniquement) +* `X-Frame-Options`: En-tête hérité qui atténue les attaques [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) +* `X-Permitted-Cross-Domain-Policies`: Contrôle le comportement inter-domaine pour les produits Adobe, comme Acrobat +* `X-Powered-By`: Informations sur le serveur web. Supprimé parce qu'il peut être utilisé dans des attaques simples +* `X-XSS-Protection`: L'en-tête hérité qui tente d'atténuer [les attaques XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), mais rend les choses pires, alors le casque le désactive + +Chaque en-tête peut être configuré ou désactivé. Pour en savoir plus à ce sujet, veuillez vous rendre sur [son site de documentation][helmet]. + +Installer le casque comme n'importe quel autre module : + +```bash +$ npm install helmet +``` + +Ensuite, pour l'utiliser dans votre code: + +```js +// ... + +const helmet = require('helmet'); +app.use(helmet()); + +// ... +``` + +## Réduire la prise d'empreintes digitales + +It can help to provide an extra layer of security to reduce the ability of attackers to determine +the software that a server uses, known as "fingerprinting." Bien que ce ne soit pas un problème de sécurité en soi, +réduisant la capacité d'empreinte digitale d'une application améliore sa position globale de sécurité. +Le logiciel serveur peut être imprimé par des empreintes digitales dans la manière dont il répond à des requêtes spécifiques, par exemple dans +les en-têtes de réponse HTTP. + +By default, Express sends the `X-Powered-By` response header that you can +disable using the `app.disable()` method: + +```js +app.disable('x-powered-by'); +``` + + + +Désactiver l'en-tête \`X-Powered-By n'empêche pas un attaquant sophistiqué de déterminer +qu'une application exécute Express. Cela peut décourager une exploitation occasionnelle, mais il existe d'autres moyens pour +de déterminer si une application exécute Express. + + + +Express envoie également ses propres messages formatés "404 Not Found" et les messages d'erreur de formatteur +de réponse. Celles-ci peuvent être modifiées par +[ajouter votre propre gestionnaire non trouvé](/en/starter/faq#how-do-i-handle-404-responses) +et +[écrire votre propre gestionnaire d'erreur](/en/guide/error-handling#writing-error-handlers) : + +```js +// last app.use calls right before app.listen(): + +// custom 404 +app.use((req, res, next) => { + res.status(404). end("Désolé ne peut pas trouver cela!"); +}); + +// application de gestion d'erreurs personnalisée +. se(err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Quelque chose s'est cassé !'); +}); +``` + +## Utiliser les cookies en toute sécurité + +Pour vous assurer que les cookies n'ouvrent pas votre application aux exploitations, n'utilisez pas le nom des cookies de session par défaut et définissez les options de sécurité des cookies de manière appropriée. + +Il y a deux principaux modules de session de cookies du middleware : + +* [express-session](https://www.npmjs.com/package/express-session) qui remplace le middleware `express.session` intégré à Express 3.x. +* [cookie-session](https://www.npmjs.com/package/cookie-session) qui remplace le middleware `express.cookieSession` intégré à Express 3.x. + +La principale différence entre ces deux modules est la façon dont ils enregistrent les données de session des cookies. Le middleware [express-session](https://www.npmjs.com/package/express-session) stocke les données de session sur le serveur ; il n'enregistre que l'ID de session dans le cookie lui-même, pas les données de session. Par défaut, il utilise du stockage en mémoire et n'est pas conçu pour un environnement de production. En production, vous devrez configurer un magasin de session évolutif ; voir la liste des [magasins de sessions compatibles] (https://github.com/expressjs/session#compatible-session-stores). + +En revanche, [cookie-session](https://www.npmjs.com/package/cookie-session) middleware implémente un stockage soutenu par des cookies : il sérialise la session entière au cookie, plutôt qu'une simple clé de session. Ne l'utilisez que lorsque les données de session sont relativement petites et facilement encodées en tant que valeurs primitives (plutôt que d'objets). Bien que les navigateurs soient supposés supporter au moins 4096 octets par cookie, pour vous assurer de ne pas dépasser la limite, ne pas dépasser une taille de 4093 octets par domaine. Sachez également que les données des cookies seront visibles par le client, donc s'il y a une raison de le garder sécurisé ou obscur, alors `express-session` pourrait être un meilleur choix. + +### Ne pas utiliser le nom du cookie de session par défaut + +Utiliser le nom par défaut des cookies de session peut ouvrir votre application à des attaques. Le problème de sécurité posé est similaire à `X-Powered-By`: un attaquant potentiel peut l'utiliser pour empreinte digitale le serveur et les attaques ciblées en conséquence. + +Pour éviter ce problème, utilisez des noms génériques de cookies; par exemple en utilisant [express-session](https://www.npmjs.com/package/express-session) middleware: + +```js +const session = require('express-session'); +app.set('trust proxy', 1); // trust first proxy +app. se( + session({ + secret: 's3Cur3', + name: 'sessionId', + }) +); +``` + +### Définir les options de sécurité des cookies + +Définissez les options suivantes des cookies pour améliorer la sécurité : + +* `secure` - Permet au navigateur d'envoyer le cookie uniquement via HTTPS. +* `httpOnly` - Assure que le cookie est envoyé uniquement sur HTTP(S), et non sur le JavaScript du client, aidant à se protéger contre les attaques de scripts intersites. +* `domain` - indique le domaine du cookie; utilisez-le pour comparer avec le domaine du serveur dans lequel l'URL est demandée. S'ils correspondent alors vérifiez l'attribut path suivant. +* `path` - indique le chemin du cookie; utilisez-le pour comparer le chemin de la requête. Si cela et le domaine correspondent, alors envoyez le cookie dans la requête. +* `expires` - utiliser pour définir la date d'expiration des cookies persistants. + +Voici un exemple utilisant [cookie-session](https://www.npmjs.com/package/cookie-session) middleware: + +```js +const session = require('cookie-session'); +const express = require('express'); +const app = express(); + +const expiryDate = new Date(Date.now() + 60 * 60 * 1000); // 1 hour +app.use( + session({ + name: 'session', + keys: ['key1', 'key2'], + cookie: { + secure: true, + httpOnly: true, + domain: 'example.com', + path: 'foo/bar', + expires: expiryDate, + }, + }) +); +``` + +## Empêcher les attaques par force brute contre l'autorisation + +Assurez-vous que les terminaux de connexion sont protégés pour rendre les données privées plus sécurisées. + +Une technique simple et puissante est de bloquer les tentatives d'autorisation à l'aide de deux mesures : + +1. Le nombre de tentatives échouées consécutives par le même nom d'utilisateur et adresse IP. +2. Le nombre de tentatives échouées depuis une adresse IP sur une longue période. Par exemple, bloquer une adresse IP si elle fait 100 tentatives échouées en un jour. + +[rate-limiter-flexible](https://github.com/animir/node-rate-limiter-flexible) package provides tools to make this technique easy and fast. Vous pouvez trouver [un exemple de protection brute dans la documentation] (https://github.com/animir/node-rate-limiter-flexible/wiki/Overall-example#login-endpoint-protection) + +## Assurez-vous que vos dépendances sont sécurisées + +Utiliser npm pour gérer les dépendances de votre application est puissant et pratique. Mais les paquets que vous utilisez peuvent contenir des vulnérabilités de sécurité critiques qui pourraient également affecter votre application. La sécurité de votre application est aussi forte que le « lien le plus faible » dans vos dépendances. + +Depuis npm@6, npm vérifie automatiquement chaque demande d'installation. Vous pouvez également utiliser `npm audit` pour analyser votre arborescence des dépendances. + +```bash +Audit npm $ +``` + +Si vous voulez être plus sécurisé, considérez [Snyk](https://snyk.io/). + +Snyk offre à la fois un [outil de ligne de commande] (https://www.npmjs.com/package/snyk) et une [intégration Github](https://snyk.io/docs/github) qui vérifie votre application contre [la base de données de vulnérabilité open source] (https://snyk.io/vuln/) pour toutes les vulnérabilités connues dans vos dépendances. Installez le CLI comme suit: + +```bash +$ npm install -g snyk +$ cd votre-application +``` + +Utilisez cette commande pour tester les vulnérabilités de votre application : + +```bash +$ test snyk +``` + +### Éviter les autres vulnérabilités connues + +Gardez un œil sur [Node Security Project](https://npmjs.com/advisories) ou [Snyk](https://snyk.io/vuln/) qui peuvent affecter Express ou d'autres modules que votre application utilise. En général, ces bases de données sont d'excellentes ressources pour la connaissance et les outils sur la sécurité des nœuds. + +Enfin, les applications Express—comme toutes les autres applications web—peuvent être vulnérables à diverses attaques sur le Web. Familiarisez-vous avec les [vulnérabilités web connues] (https://www.owasp.org/www-project-top-ten/) et prenez des précautions pour les éviter. + +## Considérations supplémentaires + +Voici quelques autres recommandations de l'excellent [Liste de contrôle de sécurité Node.js](https://blog.risingstack.com/node-js-security-checklist/). Reportez-vous à cet article de blog pour tous les détails sur ces recommandations : + +* Filtrer et nettoyer toujours les entrées de l'utilisateur pour se protéger contre les attaques de script intersite (XSS) et d'injection de commandes. +* Protégez contre les attaques d'injection SQL en utilisant des requêtes paramétrées ou des requêtes préparées. +* Utilisez l'outil [sqlmap](http://sqlmap.org/) pour détecter les vulnérabilités d'injection SQL dans votre application. +* Utilisez les outils [nmap](https://nmap.org/) et [sslyze](https://github.com/nabla-c0d3/sslyze) pour tester la configuration de vos codes SSL, , et renégociation ainsi que la validité de votre certificat. +* Utilisez [safe-regex](https://www.npmjs.com/package/safe-regex) pour vous assurer que vos expressions régulières ne sont pas susceptibles d'attaques [déni de service d'expression régulière](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS). + +[helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/fr/advanced/healthcheck-graceful-shutdown.md b/src/content/pages/fr/advanced/healthcheck-graceful-shutdown.md new file mode 100644 index 0000000000..25736a4538 --- /dev/null +++ b/src/content/pages/fr/advanced/healthcheck-graceful-shutdown.md @@ -0,0 +1,28 @@ +--- +title: Tests de santé et arrêt gracieux +description: Apprenez comment mettre en œuvre des contrôles de santé et une fermeture gracieuse dans les applications Express pour améliorer la fiabilité, gérer les déploiements et s'intégrer avec les équilibreurs de charge comme Kubernetes. +--- + +## Arrêt gracieux + +Lorsque vous déployez une nouvelle version de votre application, vous devez remplacer la version précédente. Le gestionnaire de processus que vous utilisez enverra d'abord un signal SIGTERM à l'application pour l'informer qu'il sera tué. Une fois que l'application reçoit ce signal, elle devrait cesser d'accepter de nouvelles requêtes, terminer toutes les demandes en cours, nettoyer les ressources utilisées, y compris les connexions à la base de données et les verrous de fichiers puis quitter. + +### Exemple + +```js +const server = app.listen(port); + +process.on('SIGTERM', () => { + debug('SIGTERM signal received: closing HTTP server'); + server.close(() => { + debug('HTTP server closed'); + }); +}); +``` + +## Examens de santé + +Un répartiteur de charge utilise des contrôles de santé pour déterminer si une instance de l'application est saine et peut accepter les demandes. Par exemple, [Kubernetes a deux examens de santé](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/): + +- `liveness`, qui détermine quand redémarrer un conteneur. +- `readiness`, qui détermine quand un conteneur est prêt à accepter le trafic. Lorsqu'un pod n'est pas prêt, il est retiré des répartiteurs de charge du service. diff --git a/src/content/pages/fr/advanced/security-updates.mdx b/src/content/pages/fr/advanced/security-updates.mdx new file mode 100644 index 0000000000..d4439e7afb --- /dev/null +++ b/src/content/pages/fr/advanced/security-updates.mdx @@ -0,0 +1,87 @@ +--- +title: Mises à jour de sécurité +description: Examinez les dernières mises à jour de sécurité et correctifs pour Express.js, y compris les listes de vulnérabilité détaillées pour différentes versions pour aider à maintenir une application sécurisée. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Les vulnérabilités de Node.js affectent directement Express. Therefore, keep a watch on Node.js +vulnerabilities and make sure you are using the latest +stable version of Node.js. + + + +La liste ci-dessous énumère les vulnérabilités Express qui ont été corrigées dans la mise à jour de version spécifiée. + + + +Si vous pensez avoir découvert une faille de sécurité dans Express, veuillez consulter [Politiques et procédures de sécurité +de sécurité [/en/resources/contributing#security-policies-and-procedures). + + + +## 4.x + +* 4.21.2 + * La dépendance `path-to-regexp` a été mise à jour pour répondre à un [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +* 4.21.1 + * Le `cookie` de dépendance a été mis à jour pour répondre à un [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), cela peut affecter votre application si vous utilisez `res.cookie`. +* 4.20.0 + * Correction de la vulnérabilité XSS dans `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + * La dépendance `serve-static` a été mise à jour pour adresser un [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). + * La dépendance `send` a été mise à jour pour répondre à un [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + * La dépendance `path-to-regexp` a été mise à jour pour répondre à un [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + * La dépendance `body-parser` a été mise à jour pour administrer un [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), cela peut affecter votre application si vous aviez l'url en cours d'activation. +* 4.19.0, 4.19.1 + * Correction de la vulnérabilité de redirection ouverte dans `res.location` et `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +* 4.17.3 + * La dépendance `qs` a été mise à jour pour répondre à un [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). Cela peut affecter votre application si les API suivantes sont utilisées: `req.query`, `req.body`, `req.param`. +* 4.16.0 + * La dépendance `transférée` a été mise à jour pour répondre à un [vulnerability](https://npmjs.com/advisories/527). Cela peut affecter votre application si les API suivantes sont utilisées: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + * La dépendance `mime` a été mise à jour pour répondre à un [vulnerability](https://npmjs.com/advisories/535), mais ce problème n'a pas d'impact sur Express. + * La dépendance `send` a été mise à jour pour fournir une protection contre une vulnérabilité [Node.js 8.5.0](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). Ceci n'affecte que l'exécution Express sur la version spécifique de Node.js 8.5.0. +* 4.15.5 + * La dépendance `debug` a été mise à jour pour répondre à un [vulnerability](https://snyk.io/vuln/npm:debug:20170905), mais ce problème n'a pas d'impact sur Express. + * La dépendance `fresh` a été mise à jour pour répondre à un [vulnerability](https://npmjs.com/advisories/526). Cela affectera votre application si les API suivantes sont utilisées: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. +* 4.15.3 + * La dépendance `ms` a été mise à jour pour adresser un [vulnerability](https://snyk.io/vuln/npm:ms:20170412). Cela peut affecter votre application si des chaînes de caractères non fiables sont passées à l'option `maxAge` dans les APIs suivantes: `express.static`, `res.sendfile` et `res.sendFile`. +* 4.15.2 + * La dépendance `qs` a été mise à jour pour répondre à un [vulnerability](https://snyk.io/vuln/npm:qs:20170213), mais ce problème n'a pas d'impact sur Express. Mettre à jour la version 4.15.2 est une bonne pratique, mais pas nécessaire pour résoudre la vulnérabilité. +* 4.11.1 + * Correction de la vulnérabilité de divulgation de chemin racine dans `express.static`, `res.sendfile` et `res.sendFile` +* 4.10.7 + * Correction de la vulnérabilité de redirection ouverte dans `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 4.8.8 + * Correction de vulnérabilités de traversée de répertoire dans `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +* 4.8.4 + * Node.js 0.10 peut fuir `fd`s dans certaines situations qui affectent `express.static` et `res.sendfile`. Des requêtes malveillantes pourraient provoquer une fuite de `fd`s et éventuellement entraîner des erreurs `EMFILE` et une incapacité du serveur. +* 4.8.0 + * Les tableaux d'analyse qui ont des index extrêmement élevés dans la chaîne de requête peuvent faire que le processus est à court de mémoire et planter le serveur. + * Les objets de chaîne de requête extrêmement imbriqués peuvent bloquer le processus et rendre le serveur temporairement inadapté. + +## 3.x + + +\*\*Express 3.x EST END-OF-LIFE ET AUCUNE LONGER MAINTENUE \*\* + +Les problèmes connus et inconnus de sécurité et de performance dans 3.x n'ont pas été résolus depuis la dernière mise à jour (1 août 2015). Il est fortement recommandé d'utiliser la dernière version de Express. + +Si vous ne pouvez pas mettre à jour après la version 3.x, veuillez considérer [les options de support commercial](/en/support#commercial-support-options). + + + +* 3.19.1 + * Correction de la vulnérabilité de divulgation de chemin racine dans `express.static`, `res.sendfile` et `res.sendFile` +* 3.19.0 + * Correction de la vulnérabilité de redirection ouverte dans `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 3.16.10 + * Correction de vulnérabilités de traversée de répertoire dans `express.static`. +* 3.16.6 + * Node.js 0.10 peut fuir `fd`s dans certaines situations qui affectent `express.static` et `res.sendfile`. Des requêtes malveillantes pourraient provoquer une fuite de `fd`s et éventuellement entraîner des erreurs `EMFILE` et une incapacité du serveur. +* 3.16.0 + * Des tableaux d'analyse qui ont des index extrêmement élevés dans la chaîne de requête peuvent faire que le processus est à court de mémoire et planter le serveur. + * Les objets de chaîne de requête extrêmement imbriqués peuvent bloquer le processus et rendre le serveur temporairement inadapté. +* 3.3.0 + * La réponse 404 d'une tentative de substitution de méthode non supportée était susceptible d'attaques de type cross-site scripting. diff --git a/src/content/pages/fr/guide/database-integration.mdx b/src/content/pages/fr/guide/database-integration.mdx new file mode 100644 index 0000000000..312c34f538 --- /dev/null +++ b/src/content/pages/fr/guide/database-integration.mdx @@ -0,0 +1,503 @@ +--- +title: Intégration de la base de données +description: Découvrez comment intégrer différentes bases de données avec les applications Express.js, y compris des exemples de configuration pour MongoDB, MySQL, PostgreSQL, et plus encore. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Ajouter la possibilité de connecter des bases de données à des applications Express est juste une question de charger un pilote Node.js approprié pour la base de données dans votre application. Ce document explique brièvement comment ajouter et utiliser certains des modules Node.js les plus populaires pour les systèmes de base de données dans votre application Express : + +* [Cassandra](#cassandra) +* [Couchbase](#couchbase) +* [CouchDB](#couchdb) +* [LevelDB](#leveldb) +* [MySQL](#mysql) +* [MongoDB](#mongodb) +* [Neo4j](#neo4j) +* [Oracle](#oracle) +* [PostgreSQL](#postgresql) +* [Redis](#redis) +* [Serveur SQL](#sql-server) +* [SQLite](#sqlite) +* [Elasticsearch](#elasticsearch) + + + +Ces pilotes de bases de données sont parmi les nombreux qui sont disponibles. Pour d'autres options, recherchez sur le site +[npm](https://www.npmjs.com/). + + + +## Cassandra + +**Module** : [cassandra-driver](https://github.com/datastax/nodejs-driver) + +### Installation + +```bash +$ npm install cassandra-driver +``` + +### Exemple + +```js +const cassandra = require('cassandra-driver'); +const client = new cassandra.Client({ contactPoints: ['localhost'] }); + +client. xecute('select key from system.local', (err, result) => { + if (err) throw err; + console.log(result.rows[0]); +}); +``` + +## Couchbase + +**Module** : [couchnode](https://github.com/couchbase/couchnode) + +### Installation + +```bash +$ npm install couchbase +``` + +### Exemple + +```js +const couchbase = require('couchbase'); +const bucket = new couchbase.Cluster('http://localhost:8091').openBucket('bucketName'); + +// ajoute un document à un bucket +bucket. nsert('document-key', { name: 'Matt', shoeSize: 13 }, (err, result) => { + if (err) { + console. og(err); + } autre { + console. og(result); + } +}); + +// obtient tous les documents de taille de chaussures 13 +const n1ql = 'SELECT d. FROM `bucketName` d WHERE shoeSize = $1'; +const query = N1qlQuery. romString(n1ql); +bucket.query(query, [13], (err, result) => { + if (err) { + console. og(err); + } else { + console.log(result); + } +}); +``` + +## CouchDB + +**Module** : [nano](https://github.com/dscape/nano) + +### Installation + +```bash +$ npm install nano +``` + +### Exemple + +```js +const nano = require('nano')('http://localhost:5984'); +nano.db.create('books'); +const books = nano.db. se('livress'); + +// Insérer un document dans la base de données de livres +. nsert({ name: 'L'Art de la guerre' }, null, (err, body) => { + if (err) { + console. og(err); + } autre { + console. og(body); + } +}); + +// Obtenez une liste de tous les livres +livres. ist((err, body) => { + if (err) { + console. og(err); + } else { + console.log(body.rows); + } +}); +``` + +## LevelDB + +**Module** : [levelup](https://github.com/rvagg/node-levelup) + +### Installation + +```bash +$ npm install levelup levelup level down +``` + +### Exemple + +```js +const levelup = require('levelup'); +const db = levelup('./mydb'); + +db. ut('name', 'LevelUP', (err) => { + if (err) return console.log('Ooops!', err); + + db. et('name', (err, value) => { + if (err) return console. og('Ooops!', err); + + console.log(`name=${value}`); + }); +}); +``` + +## MySQL + +**Module** : [mysql](https://github.com/felixge/node-mysql/) + +### Installation + +```bash +$ npm install mysql +``` + +### Exemple + +```js +const mysql = require('mysql'); +const connection = mysql. reateConnection({ + hôte: 'localhost', + user: 'dbuser', + password: 's3kreee7', + database: 'my_db', +}); + +connexion. onnect(); + +connection.query('SELECT 1 + 1 AS solution', (err, rows, fields) => { + if (err) throw err; + + console. og('La solution est : ', lignes[0].solution); +}); + +connection.end(); +``` + +## MongoDB + +**Module** : [mongodb](https://github.com/mongodb/node-mongodb-native) + +### Installation + +```bash +$ npm install mongodb +``` + +### Exemple (v2.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { + if (err) throw err; + + db. ollection('mammifères) + .find() + . oArray((err, result) => { + if (err) throw err; + + console. og(résultat); + }); +}); +``` + +### Exemple (v3.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, client) => { + if (err) throw err; + + const db = client. b('animaux'); + + db.collection('mammifères) + .find() + . oArray((err, result) => { + if (err) throw err; + + console. og(résultat); + }); +}); +``` + +Si vous voulez un pilote de modèle objet pour MongoDB, regardez [Mongoose](https://github.com/LearnBoost/mongoose). + +## Neo4j + +**Module** : [neo4j-driver](https://github.com/neo4j/neo4j-javascript-driver) + +### Installation + +```bash +$ npm install neo4j-driver +``` + +### Exemple + +```js +const neo4j = require('neo4j-driver'); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth. asic('neo4j', 'letmein')); + +const session = driver.session(); + +session.readTransaction((tx) => { + return tx + . un('MATCH (n) RETURN count(n) AS count') + .then((res) => { + console.log(res.records[0]. et('count')); + }) + .catch((error) => { + console. og(erreur); + }); +}); +``` + +## Oracle + +**Module** : [oracledb](https://github.com/oracle/node-oracledb) + +### Installation + +REMARQUE : [Voir les conditions préalables à l'installation] (https://github.com/oracle/node-oracledb#-installation). + +```bash +$ npm install oracledb +``` + +### Exemple + +```js +const oracledb = require('oracledb'); +const config = { + utilisateur: '', + mot de passe : '', + connectString: 'localhost:1521/orcl', +}; + +fonction async getEmployee(empId) { + let conn; + + essayer { + conn = wait oracledb. etConnection(config); + + résultat const = attendre conn. xecute('select * des employés où employee_id = :id', [empId]); + + console. og(result.rows[0]); + } attraper (err) { + console. og('Aïe ! , erreur); + } enfin { + if (conn) { + // conn assignment fonctionné, ont besoin de fermer + attendent conn. perte(); + } + } +} + +getEmployee(101); +``` + +## PostgreSQL + +**Module** : [pg-promise](https://github.com/vitaly-t/pg-promise) + +### Installation + +```bash +$ npm install pg-promise +``` + +### Exemple + +```js +const pgp = require('pg-promise')(/* options */); +const db = pgp('postgres://username:password@host:port/database'); + +db.one('SELECT $1 AS valeur', 123) + . hen((data) => { + console.log('DATA:', data.value); + }) + . atch((error) => { + console.log('ERROR:', error); +}); +``` + +## Redis + +**Module** : [redis](https://github.com/mranney/node_redis) + +### Installation + +```bash +$ npm install redis +``` + +### Exemple + +```js +const redis = require('redis'); +const client = redis.createClient(); + +client.on('error', (err) => { + console.log(`Error ${err}`); +}); + +client. et('string key', 'string val', redis.print); +client.hset('hash key', 'hashtest 1', 'some value', redis.print); +client. set(['hash key', 'hashtest 2', 'une autre valeur'], redis.print); client + +. keys('clé de hachage', (err, replies) => { + console.log(`${replies.length} réponses:`); + + réponses. orEach((reply, i) => { + console. og(` ${i}: ${reply}`); + }); + + client.quit(); +}); +``` + +## Serveur SQL + +**Module** : [tedious](https://github.com/tediousjs/tedious) + +### Installation + +```bash +$ npm install tedious +``` + +### Exemple + +```js +const Connection = require('tedious').Connexion; +const Request = require('tedious'). équête; + +const config = { + serveur: 'localhost', + authentification: { + type: 'default', + options: { + userName: 'your_username', // me mettre à jour + mot de passe: 'votre_mot de passed', // me mettre à jour + }, + }, +}; + +const connection = new Connection(config); + +connection. n('connect', (err) => { + if (err) { + console. og(err); + } else { + executeStatement(); + } +}); + +function executeStatement() { + request = new Request("select 123, 'bonjour world'", (err, rowCount) => { + if (err) { + console. og(err); + } autre { + console. og(`${rowCount} lignes`); + } + connexion. lose(); + }); + + request.on('row', (columns) => { + colonnes. orEach((column) => { + if (column.value === null) { + console. og('NULL'); + } else { + console.log(colonne. + } + }); + }); + + connection.execSql(request); +} +``` + +## SQLite + +**Module** : [sqlite3](https://github.com/mapbox/node-sqlite3) + +### Installation + +```bash +$ npm install sqlite3 +``` + +### Exemple + +```js +const sqlite3 = require('sqlite3').verbose(); +const db = new sqlite3.Database(':memory:'); + +db.serialize(() => { + db. un('CREATE TABLE lorem (info TEXT)'); + const stmt = db. repare('INSERT INTO lorem VALUES (?)'); + + for (let i = 0; i < 10; i++) { + stmt. un(`Ipsum ${i}`); + } + + stmt.finalize(); + + db. ach('SELECT rowid AS id, info FROM lorem', (err, row) => { + console. og(`${row.id}: ${row.info}`); + }); +}); + +db.close(); +``` + +## Elasticsearch + +**Module** : [elasticsearch](https://github.com/elastic/elasticsearch-js) + +### Installation + +```bash +$ npm install elasticsearch +``` + +### Exemple + +```js +const elasticsearch = require('elasticsearch'); +const client = elasticsearch.Client({ + hôte: 'localhost:9200', +}); + +client + . earch({ + index: 'books', + type: 'book', + corps : { + requête : { + multi_match: { + requête: 'express js', + champs: ['title', 'description'], + }, + }, + }, + }) + . hen( + (response) => { + hits const = response.hits. its; + }, + (erreur) => { + console. course(erreur.message); + } +); +``` diff --git a/src/content/pages/fr/guide/migrating-4.mdx b/src/content/pages/fr/guide/migrating-4.mdx new file mode 100644 index 0000000000..2de46d11f9 --- /dev/null +++ b/src/content/pages/fr/guide/migrating-4.mdx @@ -0,0 +1,661 @@ +--- +title: Déplacement vers Express 4 +description: Un guide pour migrer vos applications Express.js de la version 3 à la version 4, couvrant les changements dans le middleware, le routage et la façon de mettre à jour votre code base efficacement. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express 4 est un changement ininterrompu de Express 3. Cela signifie qu'une application Express 3 existante ne fonctionnera *pas* si vous mettez à jour la version Express dans ses dépendances. + +Cet article couvre : + + + +## Changements dans Express 4 + +Il y a plusieurs changements significatifs dans Express 4 : + + + +Voir aussi: + +* [Nouvelles fonctionnalités en 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +* [Migration de 3.x vers 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) + +### Changements vers le coeur Express et le système middleware + +Express 4 ne dépend plus de Connect, et supprime tous les middleware +intégrés de son cœur, à l'exception de la fonction `express.static`. Cela signifie que +Express est maintenant une framework web de routage et de middleware indépendante, et +Le versionnage et les versions Express ne sont pas affectés par les mises à jour du middleware. + +Sans middleware intégré, vous devez explicitement ajouter tout le middleware +nécessaire pour exécuter votre application. Suivez simplement ces étapes : + +1. Installez le module: `npm install --save ` +2. Dans votre application, nécessite le module : `require('module-name')` +3. Utilisez le module selon sa documentation: `app.use( ... )` + +Le tableau suivant liste les middleware Express 3 et leurs homologues dans Express 4. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Express 3Express 4
+ express.bodyParser + + body-parser + + multer +
+ express.compress + + compression +
+ express.cookieSession + + session de cookies +
+ express.cookieParser + + analyseur de cookies +
+ express.logger + + morgan +
+ express.session + + session expresse +
+ express.favicon + + favicon service +
+ express.responseTime + + temps de réponse +
+ express.errorHandler + + errorhandler +
+ express.methodOverride + + méthode-override +
+ express.timeout + + délai de connexion +
+ express.vhost + + vhost +
+ express.csrf + + csurf +
+ express.directory + + indice de service +
+ express.static + + serve-static +
+ +Voici la [liste complète] (https://github.com/senchalabs/connect#middleware) du middleware Express 4. + +Dans la plupart des cas, vous pouvez simplement remplacer l'ancienne version 3 du middleware par +son homologue Express 4. Pour plus de détails, consultez la documentation du module dans +GitHub. + +#### `app.use` accepte les paramètres + +Dans la version 4, vous pouvez utiliser un paramètre variable pour définir le chemin où les fonctions du middleware sont chargées, puis lit la valeur du paramètre à partir du gestionnaire de routes. +Par exemple : + +```js +app.use('/book/:id', (req, res, next) => { + console.log('ID:', req.params.id); + next(); +}); +``` + +### Le système de routage + +Les applications chargent implicitement le middleware de routage, donc vous n'avez plus à +vous inquiéter de l'ordre dans lequel le middleware est chargé par rapport à +le middleware `router`. + +The way you define routes is unchanged, but the routing system has two +new features to help organize your routes: + +* Une nouvelle méthode, `app.route()`, pour créer des gestionnaires de routes chaînables pour un chemin de route. +* Une nouvelle classe, `express.Router`, pour créer des gestionnaires de routes modulaires montables. + +#### méthode `app.route()` + +La nouvelle méthode `app.route()` vous permet de créer des gestionnaires de routes chaînables +pour un chemin de route. Parce que le chemin est spécifié dans un seul endroit, la création de routes modulaires est utile, tout comme la réduction de la redondance et des fautes de frappe. Pour plus d'informations +sur les routes, voir [`Router()` documentation](/en/4x/api#router). + +Voici un exemple de gestionnaires de routes enchaînés qui sont définis en utilisant la fonction `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + end('Obtenir un livre aléatoire'); + }) + . ost((req, res) => { + res.send('Ajouter un livre'); + }) + . ut((req, res) => { + res.send('Mettre à jour le livre'); +}); +``` + +#### Classe `express.Router` + +L'autre fonctionnalité qui aide à organiser les routes est une nouvelle classe, +`express.Router`, que vous pouvez utiliser pour créer des gestionnaires de routes montables modulaires +. Une instance `Router` est un middleware complet et un système de routage +; pour cette raison, elle est souvent appelée "mini-app". + +L'exemple suivant crée un routeur en tant que module, charge le middleware dans +it, définit certains itinéraires, et le monte sur un chemin sur l'application principale. + +Par exemple, créez un fichier de routeur nommé `birds.js` dans le répertoire de l'application, +avec le contenu suivant: + +```js +var express = require('express'); +var router = express.Router(); + +// middleware specific to this router +router.use((req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}); +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Ensuite, chargez le module routeur dans l'application : + +```js +var birds = require('./birds'); + +// ... + +app.use('/birds', oiseaux); +``` + +L'application sera maintenant en mesure de traiter les requêtes vers les chemins `/birds` et +`/birds/about`, et appellera le middleware `timeLog` +spécifique à la route. + +### Autres modifications + +Le tableau suivant liste d'autres changements mineurs mais importants dans Express 4 : + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ObjetDescription
Node.jsExpress 4 nécessite Node.js 0.10.x ou ultérieur et a abandonné la prise en charge de Node.js 0.8.x.
`http.createServer()` + Le module `http` n'est plus nécessaire, à moins que vous ayez besoin de travailler directement avec lui + (socket.io/SPDY/HTTPS). L'application peut être démarrée en utilisant la fonction `app.listen()`. +
`app.configure()` + La fonction `app.configure()` a été supprimée. Utilisez la fonction `process.env.NODE_ENV` ou + `app.get('env')` pour détecter l'environnement et configurer l'application en conséquence. +
`json spaces` + La propriété `json spaces` de l'application est désactivée par défaut dans Express 4. +
`req.accepted()` + Utilisez `req.accepts()`, `req.acceptsEncodings()`, `req.acceptsCharsets()`, et + `req.acceptsLanguages()`. +
`res.location()`Ne résout plus les URL relatives.
`req.params`A été un tableau ; maintenant un objet.
`res.locals`Était une fonction ; maintenant un objet.
`res.headerSent`Changé en `res.headersSent`.
`app.route`Maintenant disponible en tant que `app.mountpath`.
`res.on('header')`Supprimé.
`res.charset`Supprimé.
`res.setHeader('Set-Cookie', val)` + La fonctionnalité est maintenant limitée à définir la valeur de base des cookies. Utilisez `res.cookie()` pour ajouter une fonctionnalité + . +
+ +## Exemple de migration d'applications + +Voici un exemple de migration d'une application Express 3 vers Express 4. +Les fichiers d'intérêt sont `app.js` et `package.json`. + +### Application version 3 + +#### `app.js` + +Considérez une application Express v.3 avec le fichier `app.js` suivant : + +```js +var express = require('express'); +var routes = require('./routes'); +var user = require('. routes/utilisateur'); +var http = require('http'); +var path = require('path'); + +var app = express(); + +// toutes les applications +environnement. et('port', process.env.PORT || 3000); +app.set('vues', path.join(__dirname, 'views')); +app.set('voir engine', 'pug'); +app.use(express.favicon()); +app.use(express.logger('dev')); +app.use(express.methodOverride()); +app.use(express. ession({ secret: 'votre secret ici' })); +app.use(express.bodyParser()); +app.use(app.router); +app.use(express. tatic(path.join(__dirname, 'public'))); + +// développement seulement +if (app.get('env') === 'development') { + app. se(express.errorHandler()); +} + +app.get('/', routes.index); +app.get('/users', user.list); + +http. reateServer(app).listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + +#### `package.json` + +Le fichier `package.json` de la version 3 pourrait ressembler à +quelque chose comme ceci: + +```json +{ + "name": "application-name", + "version": "0.0. ", + "private": true, + "scripts": { + "start": "node app. s" + }, + "dépendances": { + "express": "3. 2.0", + "pug": "*" + } +} +``` + +### Processus + +Commencez le processus de migration en installant le middleware requis pour l'application +Express 4 et en mettant à jour Express et Pug vers leur dernière version +respective avec la commande suivante : + +```bash +$ npm install serve-favicon morgan method-override express-session body-parser multer errorhandler express@latest pug@latest --save +``` + +Effectuez les modifications suivantes à `app.js`: + +1. Les fonctions internes du middleware Express `express.favicon`, + `express.logger`, `express.methodOverride`, + `express.session`, `express.bodyParser` et + `express.errorHandler` ne sont plus disponibles sur l'objet + `express`. Vous devez installer leurs alternatives + manuellement et les charger dans l'application. + +2. Vous n'avez plus besoin de charger la fonction `app.router`. + Ce n'est pas un objet d'application Express 4 valide, alors supprimez le code + `app.use(app.router);`. + +3. Assurez-vous que les fonctions du middleware sont chargées dans le bon ordre - chargez `errorHandler` après avoir chargé les routes de l'application. + +### Application version 4 + +#### `package.json` + +Lancer la commande `npm` ci-dessus mettra à jour `package.json` comme suit: + +```json +{ + "name": "application-name", + "version": "0.0. ", + "private": true, + "scripts": { + "start": "node app. s" + }, + "dependencies": { + "body-parser": "^1.5.2", + "errorhandler": "^1.1. ", + "express": "^4.8.0", + "express-session": "^1. .2", + "pug": "^2.0.0", + "method-override": "^2. .2", + "morgan": "^1.2.2", + "multer": "^0.1. ", + "serve-favicon": "^2.0.1" + } +} +``` + +#### `app.js` + +Then, remove invalid code, load the required middleware, and make other +changes as necessary. Le fichier `app.js` ressemblera à ceci : + +```js +var http = require('http'); +var express = require('express'); +var routes = require('./routes'); +var user = require('. routes/utilisateur'); +var path = require('path'); + +var favicon = require('serve-favicon'); +var logger = require('morgan'); +var methodOverride = require('method-override'); +var session = require('express-session'); +var bodyParser = require('body-parser'); +var multer = require('multer'); +var errorHandler = require('errorhandler'); + +var app = express(); + +// tous environnements +application. et('port', process.env.PORT || 3000); +app.set('vues', path.join(__dirname, 'views')); +app.set('moteur de vue', 'pug'); +app.use(favicon(path.join(__dirname, '/public/favicon.ico')); +app.use(logger('dev')); +application. se(methodOverride()); +app. se( + session({ + resave: true, + saveUninitialized: true, + secret: 'uwotm8', + }) +); +app. se(bodyParser.json()); +app.use(bodyParser.urlencoded({ extended: true })); +app.use(multer()); +app.use(express.static(path.join(__dirname, 'public'))); + +app.get('/', routes. ndex); +app.get('/users', user.list); + +// gestion des erreurs du middleware doit être chargée après le chargement des routes +si (app. et('env') === 'développement') { + application. se(errorHandler()); +} + +var server = http.createServer(app); +server.listen(app. et('port'), () => { + console.log('Ecoute de serveur Express sur le port ' + app.get('port')); +}); +``` + + +Sauf si vous avez besoin de travailler directement avec le module `http` (socket.io/SPDY/HTTPS), le chargement n'est pas nécessaire et l'application peut être simplement démarrée de cette façon : + +```js +app.listen(app.get('port'), () => { + console.log('Ecouter le serveur Express sur le port ' + app.get('port')); +}); +``` + + + +### Exécuter l'application + +Le processus de migration est terminé, et l'application est maintenant une application +Express 4. Pour confirmer, lancez l'application en utilisant la commande suivante : + +```bash +$ node . +``` + +Charger [http://localhost:3000](http://localhost:3000) +et voir la page d'accueil rendue par Express 4. + +## Mise à niveau vers le générateur d'application Express 4 + +L'outil en ligne de commande pour générer une application Express est toujours +`express`, mais pour mettre à jour vers la nouvelle version, vous devez désinstaller +le générateur d'applications Express 3 puis installer le nouveau +`express-generator`. + +### Installation en cours + +Si vous avez déjà le générateur d'application Express 3 installé sur votre système, +vous devez le désinstaller : + +```bash +$ npm désinstaller -g express +``` + +Selon la façon dont vos droits de fichier et de répertoire sont configurés, +vous pourriez avoir besoin d'exécuter cette commande avec `sudo`. + +Installez maintenant le nouveau générateur : + +```bash +$ npm install -g express-generator +``` + +Selon la façon dont vos droits de fichier et de répertoire sont configurés, +vous pourriez avoir besoin d'exécuter cette commande avec `sudo`. + +Maintenant la commande `express` sur votre système est mise à jour vers le générateur +Express 4. + +### Modifications du générateur d'application + +Les options de commande et l'utilisation restent en grande partie les mêmes, avec les exceptions suivantes : + +* Suppression de l'option `--sessions`. +* Suppression de l'option `--jshtml`. +* Ajout de l'option `--hogan` pour supporter [Hogan.js](http://twitter.github.io/hogan.js/). + +### Exemple + +Exécutez la commande suivante pour créer une application Express 4 : + +```bash +$ app4 express +``` + +Si vous regardez le contenu du fichier `app4/app.js`, vous remarquerez +que toutes les fonctions du middleware (sauf `express. tatic`) requis pour +l'application est chargée en tant que modules indépendants, et le middleware `router` +n'est plus explicitement chargé dans l'application. + +Vous remarquerez également que le fichier `app.js` est maintenant un Node. , contrairement à l'application autonome générée par l'ancien générateur. + +Après avoir installé les dépendances, lancez l'application en utilisant la commande suivante : + +```bash +$ npm start +``` + +Si vous regardez le script `npm start` dans le paquet. son`fichier, +vous remarquerez que la commande qui démarre l'application est`node . bin/www`, qui était `node app.js\` +dans Express 3. + +Parce que le fichier `app.js` qui a été généré par le générateur Express 4 +est maintenant un nœud. , il ne peut plus être démarré indépendamment en tant qu'application +(sauf si vous modifiez le code). Le module doit être chargé dans un fichier Node.js +et démarré via le fichier Node.js. Le fichier Node.js est `./bin/www` +dans ce cas. + +Ni le répertoire `bin` ni le fichier `www` +sans extension n'est obligatoire pour créer une application Express ou démarrer l'application. They are +just suggestions made by the generator, so feel free to modify them to suit your +needs. + +Pour se débarrasser du répertoire `www` et garder les choses comme "Express 3 way", +supprime la ligne qui dit `module. xports = app;` à la fin du fichier +`app.js`, puis collez le code suivant à sa place: + +```js +app.set('port', process.env.PORT || 3000); + +var server = app.listen(app.get('port'), () => { + debug('Express server listening on port ' + server.address().port); +}); +``` + +Assurez-vous de charger le module `debug` en haut du fichier `app.js` en utilisant le code suivant : + +```js +var debug = require('debug')('app4'); +``` + +Ensuite, changez `"start": "node ./bin/www"` dans le fichier `package.json` en `"start": "node app.js"`. + +Vous avez maintenant déplacé la fonctionnalité de `./bin/www` vers +`app.js`. Ce changement n'est pas recommandé, mais l'exercice vous aide +à comprendre comment le `. Le fichier bin/www` fonctionne, et pourquoi le fichier `app.js` +ne démarre plus seul. diff --git a/src/content/pages/fr/guide/migrating-5.mdx b/src/content/pages/fr/guide/migrating-5.mdx new file mode 100644 index 0000000000..498ed9b852 --- /dev/null +++ b/src/content/pages/fr/guide/migrating-5.mdx @@ -0,0 +1,678 @@ +--- +title: Déplacement vers Express 5 +description: Un guide complet pour migrer vos applications Express.js de la version 4 à 5, détaillant les changements cassés, les méthodes obsolètes et les nouvelles améliorations. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +L'Express 5 n'est pas très différent de l'Express 4 ; bien qu'il maintienne la même API de base, il y a toujours des changements qui cèdent la compatibilité avec la version précédente. Par conséquent, une application construite avec Express 4 pourrait ne pas fonctionner si vous la mettez à jour pour utiliser Express 5. + +Pour installer cette version, vous devez avoir une version 18 ou supérieure de Node.js. Ensuite, exécutez la commande suivante dans le répertoire de votre application : + +```sh +npm install "express@5" +``` + +Vous pouvez ensuite exécuter vos tests automatisés pour voir ce qui échoue, et corriger les problèmes en fonction des mises à jour listées ci-dessous. Après avoir résolu des échecs de test, exécutez votre application pour voir quelles erreurs se produisent. Vous découvrirez immédiatement si l'application utilise des méthodes ou des propriétés qui ne sont pas prises en charge. + +## 5 Codemos Express + +Pour vous aider à migrer votre serveur express nous avons créé un ensemble de codemods qui vous aideront à mettre à jour automatiquement votre code vers la dernière version d'Express. + +Exécutez la commande suivante pour exécuter tous les codemods disponibles : + +```sh +npx codemod@latest @expressjs/v5-migration-recipe +``` + +Si vous voulez exécuter un code spécifique, vous pouvez exécuter la commande suivante : + +```sh +codemod@latest @expressjs/name-of-the-codemod +``` + +Vous pouvez trouver la liste des codes disponibles [here](https://codemod.link/express). + +## Changements dans Express 5 + +**Méthodes et propriétés supprimées** + + + +**Modifié** + + + +**Améliorations** + + + +## Méthodes et propriétés supprimées + +Si vous utilisez l'une de ces méthodes ou propriétés dans votre application, cela plantera. Donc, vous devrez changer votre application après la mise à jour vers la version 5. + +### app.del() + +Express 5 ne prend plus en charge la fonction `app.del()`. Si vous utilisez cette fonction, une erreur est levée. Pour enregistrer les routes HTTP DELETE, utilisez la fonction `app.delete()` à la place. + +Initialement, `del` a été utilisé à la place de `delete`, parce que `delete` est un mot-clé réservé en JavaScript. Cependant, depuis ECMAScript 6, `delete` et d'autres mots-clés réservés peuvent légalement être utilisés comme noms de propriétés. + + +Vous pouvez remplacer les signatures obsolètes par la commande suivante : + +```plaintext +codemod@latest @expressjs/route-de-to-delete +``` + + + +```js +// v4 +app.del('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); + +// v5 +application. elete('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); +``` + +### app.param(fn) + +La signature `app.param(fn)` a été utilisée pour modifier le comportement de la fonction `app.param(name, fn)`. Il est obsolète depuis la version 4.11.0, et Express 5 ne le supporte plus du tout. + +### Noms de méthodes pluralisées + +Les noms de méthodes suivantes ont été pluralisés. Dans Express 4, l'utilisation des anciennes méthodes a donné lieu à un avertissement de dépréciation. Express 5 ne les supporte plus du tout: + +`req.acceptsCharset()` est remplacé par `req.acceptsCharsets()`. + +`req.acceptsEncoding()` est remplacé par `req.acceptsEncodings()`. + +`req.acceptsLanguage()` est remplacé par `req.acceptsLanguages()`. + + +Vous pouvez remplacer les signatures obsolètes par la commande suivante : + +```plaintext +npx codemod@latest @expressjs/pluralize-method-names +``` + + + +```js +// v4 +app.all('/', (req, res) => { + req.acceptsCharset('utf-8'); + req. cceptsEncoding('br'); + req.acceptsLanguage('en'); + + // ... +}); + +// v5 +application. ll('/', (req, res) => { + req.acceptsCharsets('utf-8'); + req.acceptsEncodings('br'); + req.acceptsLanguages('en'); + + // ... +}); +``` + +### Point-virgule (:) dans le nom de app.param(name, fn) + +Un caractère de deux points (:) dans le nom de l'application`. aram(name, fn)` est un reste d'Express 3, et pour des raisons de compatibilité ascendante, Express 4 l'a supporté avec une notification de dépréciation. Express 5 l'ignorera silencieusement et utilisera le paramètre de nom sans le préfixer avec un deux-points. + +Cela ne devrait pas affecter votre code si vous suivez la documentation Express 4 de [app.param](/en/4x/api#app.param), car il ne fait aucune mention du côlon principal. + +### param(nom) + +Cette méthode potentiellement confuse et dangereuse de récupération des données de formulaire a été supprimée. Vous devrez maintenant spécifiquement chercher le nom du paramètre soumis dans l'objet `req.params`, `req.body`, ou `req.query`. + + +Vous pouvez remplacer les signatures obsolètes par la commande suivante : + +```plaintext +npx codemod@latest @expressjs/explicit-request-params +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + const id = req.param('id'); + const body = req. aram('body'); + const query = req.param('query'); + + // ... +}); + +// v5 +app.post('/user', (req, res) => { + const id = req.params. d; + const body = req.body; + const query = req.query; + + // ... +}); +``` + +### res.json(obj, statut) + +Express 5 ne prend plus en charge la signature `res.json(obj, status)`. Au lieu de cela, définissez le statut, puis enchaînez-le à la méthode `res.json()` comme ceci: `res.status(status).json(obj)`. + + +Vous pouvez remplacer les signatures obsolètes par la commande suivante : + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.json({ name: 'Ruben' }, 201); +}); + +// application v5 +. ost('/user', (req, res) => { + res.status(201).json({ name: 'Ruben' }); +}); +``` + +### res.jsonp(obj, status) + +Express 5 ne prend plus en charge la signature `res.jsonp(obj, status)`. Au lieu de cela, définissez le statut, puis enchaînez-le à la méthode `res.jsonp()` comme ceci: `res.status(status).jsonp(obj)`. + + +Vous pouvez remplacer les signatures obsolètes par la commande suivante : + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.jsonp({ name: 'Ruben' }, 201); +}); + +// v5 +app. ost('/user', (req, res) => { + res.status(201).jsonp({ name: 'Ruben' }); +}); +``` + +### res.redirect(url, statut) + +Express 5 ne prend plus en charge la signature `res.redirect(url, status)`. À la place, utilisez la signature suivante : `res.redirect(status, url)`. + + +Vous pouvez remplacer les signatures obsolètes par la commande suivante : + +```plaintext +npx codemod@latest @expressjs/redirect-arg-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('/users', 301); +}); + +// v5 +app. et('/user', (req, res) => { + res.redirect(301, '/users'); +}); +``` + +### res.redirect('back') et res.location('back') + +Express 5 ne supporte plus la chaîne magique `back` dans les méthodes `res.redirect()` et `res.location()`. À la place, utilisez la valeur `req.get('Referrer') || '/'` pour rediriger vers la page précédente. Dans Express 4, les méthodes `res.redirect('back')` et `res.location('back')` sont dépréciées. + + +Vous pouvez remplacer les signatures obsolètes par la commande suivante : + +```plaintext +codemod@latest @expressjs/back-redirect-deprecated +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('back'); +}); + +// v5 +application. et('/user', (req, res) => { + res.redirect(req.get('Referrer') || '/'); +}); +``` + +### res.send(body, statut) + +Express 5 ne prend plus en charge la signature `res.send(obj, status)`. Au lieu de cela, définissez le statut, puis enchaînez-le à la méthode `res.send()` comme ceci: `res.status(status).send(obj)`. + + +Vous pouvez remplacer les signatures obsolètes par la commande suivante : + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send({ name: 'Ruben' }, 200); +}); + +// v5 +app. et('/user', (req, res) => { + res.status(200).send({ name: 'Ruben' }); +}); +``` + +### res.send(statut) + +Express 5 ne prend plus en charge la signature `res.send(status)`, où `status` est un nombre. À la place, utilisez les `res. la fonction endStatus(statusCode)`, qui définit le code d'état de l'en-tête de réponse HTTP et envoie la version texte du code: "Non trouvée", "Erreur interne du serveur", et ainsi de suite. +Si vous avez besoin d'envoyer un numéro en utilisant les `res. la fonction end()`, guillemets le nombre pour le convertir en une chaîne, afin qu'Express ne l'interprète pas comme une tentative d'utiliser l'ancienne signature non supportée. + + +Vous pouvez remplacer les signatures obsolètes par la commande suivante : + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send(200); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendStatus(200); +}); +``` + +### res.sendfile() + +La fonction `res.sendfile()` a été remplacée par une version à chameau `res.sendFile()` dans Express 5. + +**Note:** En Express 5, `res. endFile()` utilise le paquet `mime-types` pour la détection de type MIME, qui retourne des valeurs de type de contenu différentes que Express 4 pour plusieurs types de fichiers communs: + +* Fichiers JavaScript (.js): maintenant "text/javascript" au lieu de "application/javascript" +* Fichiers JSON (.json): maintenant "application/json" au lieu de "text/json" +* Fichiers CSS (.css): maintenant "text/css" au lieu de "text/plain" +* Fichiers XML (.xml): maintenant "application/xml" au lieu de "text/xml" +* Fichiers de police (.woff): maintenant "font/woff" au lieu de "application/font-woff" +* Fichiers SVG (.svg): maintenant "image/svg+xml" au lieu de "application/svg+xml" + + +Vous pouvez remplacer les signatures obsolètes par la commande suivante : + +```plaintext +codemod@latest @expressjs/camelcase-sendfile npx +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.sendfile('/path/to/file'); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendFile('/path/to/file'); +}); +``` + +### router.param(fn) + +La signature `router.param(fn)` a été utilisée pour modifier le comportement de la fonction `router.param(name, fn)`. Il est obsolète depuis la version 4.11.0, et Express 5 ne le supporte plus du tout. + +### express.static.mime + +Dans Express 5, `mime` n'est plus une propriété exportée du champ `static`. +Utilisez le paquet [`mime-types`](https://github.com/jshttp/mime-types) pour travailler avec les valeurs de type MIME. + +**Important:** Ce changement affecte non seulement l'utilisation directe de `express.static.mime` mais aussi d'autres méthodes Express qui dépendent de la détection de type MIME, telles que `res.sendFile()`. Les types MIME suivants sont passés de Express 4 : + +* Fichiers JavaScript (.js): maintenant servi comme "text/javascript" au lieu de "application/javascript" +* Fichiers JSON (.json): maintenant servi comme "application/json" au lieu de "text/json" +* Fichiers CSS (.css): maintenant servi comme "text/css" au lieu de "text/plain" +* Fichiers HTML (): maintenant servi comme "text/html; charset=utf-8" au lieu de "text/html" +* Fichiers XML (.xml): maintenant servi comme "application/xml" au lieu de "text/xml" +* Fichiers de police (.woff): maintenant utilisé comme "font/woff" au lieu de "application/font-woff" + +```js +// v4 +express.static.mime.lookup('json'); + +// v5 +const mime = require('mime-types'); +mime.lookup('json'); +``` + +### express:journaux de débogage du routeur + +Dans Express 5, la logique de gestion du routeur est effectuée par une dépendance. Par conséquent, les journaux de débogage +pour le routeur ne sont plus disponibles dans l'espace de noms `express:`. +Dans la v4, les logs étaient disponibles sous les espaces de noms `express:router`, `express:router:layer`, +et `express:router:route`. Tous ces éléments ont été inclus dans l'espace de noms `express:*`. +En v5.1+, les logs sont disponibles dans les espaces de noms `router`, `router:layer`, et `router:route`. +Les logs de `router:layer` et `router:route` sont inclus dans l'espace de noms `router:*`. +Pour obtenir le même détail de débogage lors de l'utilisation de `express:*` dans la v4, utilisez une conjonction de +`express:*`, `router`, et `router:*`. + +```sh + +DEBUG=express:* node index.js + + +DEBUG=express:*,router,routeur:* node index.js +``` + +## Modifié + +### Syntaxe correspondante au chemin + +La syntaxe correspondante au chemin d'accès est lorsqu'une chaîne de caractères est fournie comme premier paramètre pour les API `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, et `router.use()`. Les modifications suivantes ont été apportées à la façon dont la chaîne de chemin est associée à une requête entrante : + +* Le caractère générique `*` doit avoir un nom correspondant au comportement des paramètres `:`, utilisez `/*splat` au lieu de `/*` + +```js +// v4 +app.get('/*', async (req, res) => { + res.send('ok'); +}); + +// v5 +application. et('/*splat', async (req, res) => { + res.send('ok'); +}); +``` + + +`*splat` correspond à n'importe quel chemin sans le chemin racine. Si vous avez besoin de faire correspondre le chemin racine aussi bien que `/`, vous pouvez utiliser `/{*splat}`, envelopper le joker entre parenthèses. + +```js +// v5 +app.get('/{*splat}', async (req, res) => { + res.send('ok'); +}); +``` + + + +* Le caractère optionnel `?` n'est plus pris en charge, utilisez plutôt des accolades. + +```js +// v4 +app.get('/:file.:ext?', async (req, res) => { + res.send('ok'); +}); + +// application v5 +. et('/:file{.:ext}', async (req, res) => { + res.send('ok'); +}); +``` + +* Les caractères Regexp ne sont pas pris en charge. Par exemple : + +```js +app.get('/[discussion|page]/:slug', async (req, res) => { + res.status(200).send('ok'); +}); +``` + +devrait être changé en : + +```js +app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { + res.status(200).send('ok'); +}); +``` + +* Certains caractères ont été réservés pour éviter toute confusion lors de la mise à jour (`()[]?+!`), utilisez `\` pour les échapper. +* Les noms de paramètres supportent maintenant des identifiants JavaScript valides, ou des guillemets comme `:"this"`. + +### Les promesses rejetées des middleware et des gestionnaires + +Les requêtes de middleware et les gestionnaires qui retournent les promesses rejetées sont maintenant gérées en renvoyant la valeur rejetée comme une `Erreur` vers le middleware. Cela signifie que l'utilisation des fonctions `async` comme middleware et des gestionnaires est plus facile que jamais. Lorsqu'une erreur est levée dans une fonction `async` ou qu'une promesse rejetée est `attendu` dans une fonction asynchrone, ces erreurs seront passées au gestionnaire d'erreurs comme si elle appelait `next(err)`. + +Détail de la façon dont Express gère les erreurs est couvert dans la [documentation de gestion des erreurs](/en/guide/error-handling). + +### express.urlencodé + +La méthode `express.urlencoded` rend l'option `extended` `false` par défaut. + +### express.static dotfiles + +Dans Express 5, l'option `express.static` du middleware `dotfiles` par défaut est maintenant `"ignore"`. Ceci est un changement par rapport à Express 4, où les dotfiles ont été servis par défaut. En conséquence, les fichiers à l'intérieur d'un répertoire qui commence par un point (`.`), comme `. ell-known`, ne sera plus accessible et retournera une erreur **404 Not Found**. Cela peut casser la fonctionnalité qui dépend du service de répertoires de points, tels que les liens d'applications Android, et Apple Universal Links. + +Exemple de code cassé : + +```js +// v4 +app.use(express.static('public')); +``` + +Après avoir migré vers Express 5, une requête vers `/.well-known/assetlinks.json` résultera en un **404 Not Found**. + +Pour corriger ceci, servir explicitement des répertoires de points spécifiques en utilisant l'option `dotfiles: "allow"` : + +```js +// v5 +app.use('/.well-known', express.static('public/.well-known', { dotfiles: 'allow' })); +app.use(express.static('public')); +``` + +Cette approche vous permet de ne servir en toute sécurité que les répertoires de points prévus tout en conservant le comportement sécurisé par défaut pour les autres dotfiles, qui restent inaccessibles. + +### Écouter + +Dans Express 5, la méthode `app.listen` invoquera la fonction de rappel fournie par l'utilisateur (si fournie) lorsque le serveur reçoit un événement d'erreur. Dans Express 4, de telles erreurs seraient lancées. Ce changement déplace la responsabilité de gestion des erreurs vers la fonction callback dans Express 5. S'il y a une erreur, elle sera passée au callback en tant qu'argument. +Par exemple : + +```js +const server = app.listen(8080, '0.0.0.0', (error) => { + if (error) { + throw error; // e.g. EADDRINUSE + } + console.log(`Écoute sur ${JSON.stringify(server.address())}`); +}); +``` + +### routeur + +L'objet `app.router`, qui a été supprimé dans Express 4, a fait un retour dans Express 5. Dans la nouvelle version, cet objet est juste une référence au routeur de base Express, contrairement à Express 3, où une application devait explicitement la charger. + +### Req.body + +La propriété `req.body` retourne `undefined` quand le corps n'a pas été analysé. Dans Express 4, il retourne `{}` par défaut. + +### Hôte + +Dans Express 4, la fonction `req.host` a incorrectement retiré le numéro de port si elle était présente. Dans Express 5, le numéro de port est maintenu. + +### Réglages + +L'objet `req.params` a maintenant un **prototype null** lors de l'utilisation des chemins de chaîne de caractères. Cependant, si le chemin est défini avec une expression régulière, `req.params` reste un objet standard avec un prototype normal. En outre, il y a deux changements importants de comportement: + +**Les paramètres de la carte joker sont maintenant des tableaux :** + +Les jokers (par exemple, `/*splat`) capturent les segments de chemin en tant que tableau au lieu d'une seule chaîne. + +```js +app.get('/*splat', (req, res) => { + // GET /foo/bar + console.dir(req. arams); + // => [Object: null prototype] { splat: [ 'foo', 'bar' ] } +}); +``` + +**Les paramètres sans correspondance sont omis :** + +Dans Express 4, les caractères génériques sans correspondance étaient des chaînes vides (`''`) et les paramètres optionnels `:` (à l'aide de `?`) avaient une clé avec la valeur `undefined`. Dans Express 5, les paramètres incomparables sont complètement omis de `req.params`. + +```js +// v4: un joker sans correspondance est une chaîne +app.get('/*', (req, res) => { + // GET / + console.dir(req. arams); + // => { '0': '' } +}); + +// v4: un paramètre facultatif sans correspondance est une application +non définie. et('/:file.:ext?', (req, res) => { + // GET /image + console. ir(req.params); + // => { file: 'image', ext: undefined } +}); + +// v5: unmatched optional param is omitted +app.get('/:file{. ext}', (req, res) => { + // GET /image + console.dir(req. arams); + // => [Object: null prototype] { file: 'image' } +}); +``` + +### Requête + +La propriété `req.query` n'est plus une propriété accessible en écriture et est plutôt un getter. L'analyseur de requête par défaut a été changé de "étendu" à "simple". + +### Effacer les cookies + +La méthode `res.clearCookie` ignore les options `maxAge` et `expires` fournies par l'utilisateur. + +### Statut + +La méthode `res.status` n'accepte que les entiers de la plage de `100` à `999`, suivant le comportement défini par Node. , et retourne une erreur lorsque le code de statut n'est pas un entier. + +### res.vary + +Le fichier `res.vary` lance une erreur quand l'argument `field` est manquant. Dans Express 4, si l'argument a été omis, il a donné un avertissement dans la console + +## Améliorations + +### res.render() + +Cette méthode impose maintenant un comportement asynchrone pour tous les moteurs de vue, en évitant les bogues causés par les moteurs de vue qui avaient une implémentation synchronisée et qui violaient l'interface recommandée. + +### Prise en charge de l'encodage Brotli + +Express 5 prend en charge l'encodage Brotli pour les requêtes reçues des clients qui le supportent. diff --git a/src/content/pages/fr/resources/glossary.mdx b/src/content/pages/fr/resources/glossary.mdx new file mode 100644 index 0000000000..c24ebfbad7 --- /dev/null +++ b/src/content/pages/fr/resources/glossary.mdx @@ -0,0 +1,61 @@ +--- +title: Glossary +description: Un glossaire complet de termes liés à Express.js, Node.js, middleware, routing et autres concepts clés pour vous aider à comprendre et utiliser Express efficacement. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +### application + +En général, un ou plusieurs programmes sont conçus pour réaliser des opérations à des fins précises. Dans le contexte d'Express, un programme qui utilise l'API Express exécutée sur la plate-forme Node.js. Peut aussi se référer à un [objet application] (/en/api#express). + +### API + +Interface de programmation applicative. Sortez l'abréviation quand elle est utilisée pour la première fois. + +### Exprimé + +Un framework web rapide, sans avis et minimaliste pour les applications Node.js. En général, "Express" est préféré à "Express.js", bien que ce dernier soit acceptable. + +### libuv + +Une bibliothèque de support multi-plateforme qui se concentre sur les E/S asynchrones, principalement développée pour Node.js. + +### middleware + +Une fonction qui est appelée par la couche de routage Express avant le gestionnaire de requête finale, et se trouve donc au milieu entre une requête brute et la route finale. Quelques bons points de terminologie autour du middleware : + +* `var foo = require('middleware')` est appelé *requiring* ou *using* un module Node.js. Puis l'instruction `var mw = foo()` retourne typiquement le middleware. +* `app.use(mw)` est appelé *adding the middleware to the global processing stack*. +* `app.get('/foo', mw, function (req, res) { ... })` est appelé _ajoutant le middleware à la pile de traitement "GET /foo". + +### Node.js + +Une plate-forme logicielle utilisée pour construire des applications réseau évolutives. Node.js utilise JavaScript comme langage de script, et obtient un débit élevé via des E/S non-bloquantes et une boucle d'événements à un seul thread. Voir [nodejs.org](https://nodejs.org/en/). **Note d'utilisation**: Initialement, "Node.js," ensuite "Node". + +### open-source, open source + +Lorsqu'il est utilisé comme adjectif, trait d'union, par exemple : "Il s'agit d'un logiciel open-source". Voir [Logiciel open source sur Wikipédia](http://en.wikipedia.org/wiki/Open-source_software). + + + +Bien qu'il soit courant de ne pas faire de trait d'union avec ce terme, nous utilisons les règles anglaises standards pour +tiret de trait d'union d'un adjectif composé. + + + +### demande + +Une requête HTTP. Un client envoie un message de requête HTTP à un serveur, qui retourne une réponse. La requête doit utiliser une de plusieurs [méthodes de requête] (https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) telles que GET, POST, etc. + +### réponse + +Une réponse HTTP. Un serveur retourne un message de réponse HTTP au client. La réponse contient des informations sur l'état de la requête et peut également contenir le contenu demandé dans le corps du message. + +### route + +Partie d'une URL qui identifie une ressource. Par exemple, dans `http://foo.com/products/id`, "/products/id" est la route. + +### routeur + +Voir [router](/en/api#router) dans la référence de l'API. diff --git a/src/content/pages/fr/resources/utils.md b/src/content/pages/fr/resources/utils.md new file mode 100644 index 0000000000..f00e8ddbd7 --- /dev/null +++ b/src/content/pages/fr/resources/utils.md @@ -0,0 +1,22 @@ +--- +title: Utilitaires Express +description: Découvrez des modules utilitaires liés à Express.js et Node.js, y compris des outils pour les cookies, la protection CSRF, l'analyse d'URL, le routage, et plus encore pour améliorer vos applications. +--- + +## Fonctions utilitaires Express + +L'organisation GitHub [pillarjs](https://github.com/pillarjs) contient un certain nombre de modules +pour des fonctions utilitaires qui peuvent être généralement utiles. + +| Modules utilitaires | Libellé | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| [cookies](https://www.npmjs.com/package/cookies) | Obtenez et définissez les cookies HTTP(S) qui peuvent être signés pour éviter toute altération en utilisant Keygrip. Peut être utilisé avec la bibliothèque HTTP Node.js ou comme middleware Express. | +| [csrf](https://www.npmjs.com/package/csrf) | Contient la logique derrière la création et la vérification de jetons CSRF. Utilisez ce module pour créer un middleware CSRF personnalisé. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Fonction à invoquer comme dernière étape pour répondre à la requête HTTP. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Analyser une URL avec le cache. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Transformez une chaîne de chemin de type Express, telle que \`\`/user/:name\` en une expression régulière. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Résout un chemin relatif par rapport à un chemin racine avec validation. | +| [router](https://www.npmjs.com/package/router) | Routeur de type middleware simple. | +| [send](https://www.npmjs.com/package/send) | Bibliothèque pour le streaming des fichiers en tant que réponse HTTP, avec le support des réponses partielles (gammes), la négociation conditional-GET et les événements granulaires. | + +Pour des modules supplémentaires liés au protocole HTTP, voir [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/fr/support.md b/src/content/pages/fr/support.md new file mode 100644 index 0000000000..5f5398f7f2 --- /dev/null +++ b/src/content/pages/fr/support.md @@ -0,0 +1,23 @@ +--- +title: Support de la version +description: Trouvez des informations sur le calendrier de support des différentes versions de Express.js, y compris les versions actuellement maintenues et les politiques de fin de vie. +--- + +Seule la dernière version d'une ligne de publication majeure est prise en charge. + +Les versions qui sont EdlV (fin de vie) _peuvent_ recevoir des mises à jour pour les vulnérabilités critiques de sécurité, mais l'équipe Express n'offre aucune garantie et ne prévoit pas de résoudre ou de corriger les problèmes rencontrés. + +| Version majeure | Version minimale de Node.js | Date de début du support | Date de fin du support | +| ------------------------------------------- | ------------------------------------------- | ------------------------ | ---------------------- | +| [**v5.x**](/en/5x/api) | 18 | Septembre 2024 | **en cours** | +| [**v4.x**](/en/4x/api) | 0.10.0 | Avril 2014 | **en cours** | +| [**v3.x**](/en/3x/api) | 0.8.0 | Octobre 2012 | Juillet 2015 | +| [**v2.x**](/2x/) | 0.4.1 | Mars 2011 | Juillet 2012 | +| **v1.x** | 0.2.0 | Décembre 2010 | Mars 2011 | +| **v0.14.x** | 0.1.98 | Décembre 2010 | Décembre 2010 | + +## Options de support commercial + +Si vous ne pouvez pas mettre à jour une version prise en charge de Express, veuillez contacter l'un de nos partenaires pour recevoir les mises à jour de sécurité : + +- [Support des Héros sans fin](http://www.herodevs.com/support/express-nes?utm_source=expressjs&utm_medium=link&utm_campaign=express_eol_page) diff --git a/src/content/pages/it/advanced/best-practice-performance.md b/src/content/pages/it/advanced/best-practice-performance.md new file mode 100644 index 0000000000..c0a8ac9a9c --- /dev/null +++ b/src/content/pages/it/advanced/best-practice-performance.md @@ -0,0 +1,305 @@ +--- +title: 'Migliori pratiche di produzione: prestazioni e affidabilità' +description: Scopri le migliori pratiche di performance e affidabilità per le app Express in produzione, coprendo ottimizzazioni di codice e impostazioni ambientali per prestazioni ottimali. +--- + +Questo articolo discute le migliori pratiche di performance e affidabilità per le applicazioni Express distribuite alla produzione. + +Questo argomento rientra chiaramente nel mondo dei "devops", che abbraccia sia lo sviluppo tradizionale che le operazioni. Di conseguenza, le informazioni sono suddivise in due parti: + +- Cose da fare nel tuo codice (la parte dev): + - [Usa compressione gzip](#use-gzip-compression) + - [Non utilizzare le funzioni sincrone](#dont-use-synchronous-functions) + - [Effettua la registrazione corretta](#do-logging-correctly) + - [Maneggiare correttamente le eccezioni](#handle-exceptions-properly) +- Cose da fare nel tuo ambiente / configurazione (la parte ops): + - [Imposta NODE_ENV a "production"](#set-node_env-to-production) + - [Assicurati che l'app si riavvii automaticamente](#ensure-your-app-automatically-restarts) + - [Esegui la tua app in un cluster](#run-your-app-in-a-cluster) + - [Cache request results](#cache-request-results) + - [Usa un balancer](#use-a-load-balancer) + - [Usa un proxy inverso](#use-a-reverse-proxy) + +## Cose da fare nel tuo codice + +Ecco alcune cose che puoi fare nel tuo codice per migliorare le prestazioni della tua applicazione: + +- [Usa compressione gzip](#use-gzip-compression) +- [Non utilizzare le funzioni sincrone](#dont-use-synchronous-functions) +- [Effettua la registrazione corretta](#do-logging-correctly) +- [Maneggiare correttamente le eccezioni](#handle-exceptions-properly) + +### Usa compressione gzip + +La compressione di Gzip può ridurre notevolmente la dimensione del corpo della risposta e quindi aumentare la velocità di una web app. Usa il middleware [compression](https://www.npmjs.com/package/compression) per la compressione gzip nella tua app Express. Per esempio: + +```js +const compression = require('compression'); +const express = require('express'); +const app = express(); + +app.use(compression()); +``` + +Per un sito web ad alto traffico in produzione, il modo migliore per mettere in atto la compressione è implementarla a un livello di proxy inverso (vedere [Usa un proxy inverso](#use-a-reverse-proxy)). In tal caso, non è necessario utilizzare middleware di compressione. Per maggiori dettagli sull'attivazione della compressione gzip in Nginx, vedere [Modulo ngx_http_gzip_module](http://nginx.org/en/docs/http/ngx_http_gzip_module) nella documentazione Nginx. + +### Non utilizzare funzioni sincrone + +Le funzioni e i metodi sincroni legano il processo di esecuzione fino al loro ritorno. Una singola chiamata ad una funzione sincrona potrebbe tornare in pochi microsecondi o millisecondi, tuttavia nei siti web ad alto traffico, queste chiamate si sommano e riducono le prestazioni dell'app. Evitare il loro uso in produzione. + +Sebbene Node e molti moduli forniscano versioni sincrone e asincrone delle loro funzioni, utilizzare sempre la versione asincrona in produzione. L'unico momento in cui una funzione sincrona può essere giustificata è all'avvio iniziale. + +Puoi usare il flag da riga di comando `--trace-sync-io` per stampare un avviso e uno stack trace ogni volta che la tua applicazione utilizza un'API sincrona. Naturalmente, non si desidera utilizzare questo in produzione, ma piuttosto per garantire che il codice è pronto per la produzione. Vedi la [documentazione delle opzioni a riga di comando del nodo](https://nodejs.org/api/cli#cli_trace_sync_io) per maggiori informazioni. + +### Effettuare la registrazione correttamente + +In generale, ci sono due motivi per la registrazione dalla tua app: Per il debug e per la registrazione delle attività delle app (essenzialmente, tutto il resto). Usare `console.log()` o `console.error()` per stampare i messaggi di log sul terminale è una pratica comune nello sviluppo. Ma [queste funzioni sono sincrone](https://nodejs.org/api/console#console) quando la destinazione è un terminale o un file, in modo che non siano adatti per la produzione, a meno che non convogliate l'uscita ad un altro programma. + +#### Per il debug + +Se stai registrando a fini di debug, invece di usare `console.log()`, usa uno speciale modulo di debug come [debug](https://www.npmjs.com/package/debug). Questo modulo consente di utilizzare la variabile di ambiente DEBUG per controllare quali messaggi di debug vengono inviati a `console.error()`, se presenti. Per mantenere la tua app puramente asincrona, dovresti ancora reindirizzare `console.error()` ad un altro programma. Ma allora, non stai davvero andando a debug nella produzione, vero? + +#### Per attività app + +Se stai registrando le attività delle app (ad esempio, tracciando traffico o chiamate API), invece di usare `console. og()`, usa una libreria di registrazione come [Pino](https://www.npmjs.com/package/pino), che è l'opzione più veloce ed efficiente disponibile. + +### Gestisci correttamente le eccezioni + +Le app del nodo si bloccano quando incontrano un'eccezione non catturata. Non gestire le eccezioni e intraprendere azioni appropriate renderà il tuo crash di app Express e andare offline. Se segui i consigli in [Assicurati che la tua app riavvii automaticamente](#ensure-your-app-automatically-restarts) qui sotto, allora la tua app recupererà da un crash. Fortunatamente, le applicazioni Express in genere hanno un breve tempo di avvio. Tuttavia, si desidera evitare di schiantarsi in primo luogo, e per farlo, è necessario gestire le eccezioni correttamente. + +Per garantire la gestione di tutte le eccezioni, utilizzare le seguenti tecniche: + +- [Usa try-catch](#use-try-catch) +- [Usa promesse](#use-promises) + +Prima di immergersi in questi argomenti, si dovrebbe avere una comprensione di base della gestione degli errori Node/Express: utilizzando error-first callback e gli errori di propagazione in middleware. Il nodo utilizza una convenzione "error-first callback" per restituire gli errori dalle funzioni asincrone, dove il primo parametro della funzione callback è l'oggetto errore, seguito da dati di risultato in parametri successivi. Per indicare nessun errore, passare null come primo parametro. La funzione di callback deve seguire in modo corrispondente la convenzione di callback errore-first callback per gestire in modo significativo l'errore. E in Express, la migliore pratica è quella di utilizzare la funzione next() per propagare gli errori attraverso la catena middleware. + +Per maggiori informazioni sui fondamenti della gestione degli errori, consultare: + +- [Gestione degli errori in Node.js](https://www.tritondatacenter.com/node-js/production/design/errors) + +#### Usa try-catch + +Try-catch è una struttura in linguaggio JavaScript che puoi usare per catturare le eccezioni in codice sincrono. Usa try-catch, per esempio, per gestire gli errori di analisi JSON come mostrato di seguito. + +Ecco un esempio di utilizzo di try-catch per gestire una potenziale eccezione di processo-crashing. +Questa funzione middleware accetta un parametro del campo di query denominato "params" che è un oggetto JSON. + +```js +app.get('/search', (req, res) => { + // Simulating async operation + setImmediate(() => { + const jsonStr = req.query.params; + try { + const jsonObj = JSON.parse(jsonStr); + res.send('Success'); + } catch (e) { + res.status(400).send('Invalid JSON string'); + } + }); +}); +``` + +Tuttavia, try-catch funziona solo per il codice sincrono. Poiché la piattaforma Nodo è principalmente asincrona (in particolare in un ambiente di produzione), il try-catch non prenderà molte eccezioni. + +#### Usa promesse + +Quando un errore viene lanciato in una funzione `async` o una promessa rifiutata è attesa all'interno di una funzione `async`, questi errori verranno passati al gestore degli errori come se chiamasse `next(err)` + +```js +app.get('/', async (req, res, next) => { + const data = await userData(); // If this promise fails, it will automatically call `next(err)` to handle the error. + + res.send(data); +}); + +app.use((err, req, res, next) => { + res.status(err.status ?? 500).send({ error: err.message }); +}); +``` + +Inoltre, è possibile utilizzare funzioni asincrone per il vostro middleware, e il router gestirà gli errori se la promessa fallisce, per esempio: + +```js +app.use(async (req, res, next) => { + req.locals.user = await getUser(req); + + next(); // This will be called if the promise does not throw an error. +}); +``` + +La migliore pratica è quella di gestire gli errori il più vicino possibile al sito. Quindi, mentre questo è ora gestito nel router, è meglio catturare l'errore nel middleware e gestirlo senza fare affidamento su middleware di gestione degli errori separati. + +#### Cosa non fare + +Una cosa che dovresti _non_ fare è ascoltare per l'evento `uncaughtException`, emessa quando una bolla di eccezione ritorna fino al ciclo evento. L'aggiunta di un ascoltatore di eventi per `uncaughtException` cambierà il comportamento predefinito del processo che sta incontrando un'eccezione; il processo continuerà a funzionare nonostante l'eccezione. Questo potrebbe sembrare un buon modo per impedire che la tua app si blocchi, ma continuare ad eseguire l'app dopo un'eccezione non catturata è una pratica pericolosa e non è raccomandato, perché lo stato del processo diventa inaffidabile e imprevedibile. + +Inoltre, l'utilizzo di `uncaughtException` è ufficialmente riconosciuto come [crude](https://nodejs.org/api/process#process_event_uncaughtexception). Quindi ascoltare `uncaughtException` è solo una cattiva idea. Questo è il motivo per cui consigliamo cose come più processi e supervisori: crash e riavvio è spesso il modo più affidabile per recuperare da un errore. + +Inoltre non consigliamo di utilizzare [domains](https://nodejs.org/api/domain). Generalmente non risolve il problema ed è un modulo deprecato. + +## Cose da fare nel tuo ambiente / configurazione + +Ecco alcune cose che puoi fare nel tuo ambiente di sistema per migliorare le prestazioni della tua app: + +- [Imposta NODE_ENV a "production"](#set-node_env-to-production) +- [Assicurati che l'app si riavvii automaticamente](#ensure-your-app-automatically-restarts) +- [Esegui la tua app in un cluster](#run-your-app-in-a-cluster) +- [Cache request results](#cache-request-results) +- [Usa un balancer](#use-a-load-balancer) +- [Usa un proxy inverso](#use-a-reverse-proxy) + +### Imposta NODE_ENV a "produzione" + +La variabile d' ambiente NODE_ENV specifica l' ambiente in cui un' applicazione è in esecuzione (solitamente, sviluppo o produzione). Una delle cose più semplici che puoi fare per migliorare le prestazioni è impostare NODE_ENV a `produzione`. + +Impostando NODE_ENV a "production" makes Express: + +- Modelli visualizzazione della cache. +- File CSS della cache generati dalle estensioni CSS. +- Genera messaggi di errore meno dettagliati. + +[Tests indicate](https://www.dynatrace.com/news/blog/the-drastic-effects-of-omitting-node-env-in-your-express-js-applications/) che solo facendo questo può migliorare le prestazioni dell'app di un fattore di tre! + +Se è necessario scrivere un codice specifico per l'ambiente, è possibile controllare il valore di NODE_ENV con `process.env.NODE_ENV`. Essere consapevoli che il controllo del valore di qualsiasi variabile ambientale comporta una penalità di prestazione, e quindi dovrebbe essere fatto con parsimonia. + +In fase di sviluppo, in genere imposterai le variabili di ambiente nella tua shell interattiva, ad esempio usando `export` o il tuo file `.bash_profile`. Ma in generale, non dovresti farlo su un server di produzione; invece, usa il sistema di ingresso del tuo sistema operativo (systemd). La sezione successiva fornisce maggiori dettagli sull'utilizzo del sistema di init in generale, ma l'impostazione `NODE_ENV` è così importante per le prestazioni (e facile da fare), che è evidenziata qui. + +Con il sistema, usa la direttiva `Environment` nel tuo file unitario. Per esempio: + +```sh + +Environment=NODE_ENV=production +``` + +Per ulteriori informazioni, vedere [Uso delle variabili ambientali nelle unità systemd](https://www.flatcar.org/docs/latest/setup/systemd/environment-variables/). + +### Assicurati che l'app si riavvii automaticamente + +In produzione, non vuoi che la tua applicazione sia offline, mai. Ciò significa che è necessario assicurarsi che si riavvia sia se l'applicazione si blocca e se il server stesso si blocca. Anche se si spera che nessuno di questi eventi accada, realisticamente si deve rendere conto di entrambe le eventualità mediante: + +- Utilizzando un gestore di processo per riavviare l'applicazione (e Node) quando si blocca. +- Utilizzando il sistema di init fornito dal sistema operativo per riavviare il gestore di processo quando il sistema operativo si blocca. È anche possibile utilizzare il sistema init senza un gestore di processo. + +Le applicazioni del nodo si bloccano se incontrano un'eccezione non catturata. La cosa più importante che devi fare è assicurarsi che la tua app sia ben testata e gestisca tutte le eccezioni (vedi [gestire le eccezioni correttamente](#handle-exceptions-properly) per i dettagli). Ma come un fail-safe, mettere un meccanismo in atto per garantire che se e quando l'app si blocca, si riavvierà automaticamente. + +#### Usa un gestore di processo + +In fase di sviluppo, hai avviato la tua app semplicemente dalla riga di comando con `node server.js` o qualcosa di simile. Ma fare questo in produzione è una ricetta per il disastro. Se l'app si blocca, sarà offline fino al riavvio. Per garantire il riavvio dell'app in caso di crash usa un gestore di processo. Un process-manager è un "container" per le applicazioni che facilita l'implementazione, fornisce un'elevata disponibilità e consente di gestire l'applicazione durante il runtime. + +Oltre a riavviare la tua app quando si blocca, un gestore di processo può permetterti di: + +- Ottieni informazioni sulle prestazioni di runtime e sul consumo di risorse. +- Modifica le impostazioni dinamicamente per migliorare le prestazioni. +- Clustering di controllo (pm2). + +Storicamente, era popolare usare un manager di processo Node.js come [PM2](https://github.com/Unitech/pm2). Vedere la loro documentazione se si desidera farlo. Tuttavia, si consiglia di utilizzare il sistema init per la gestione dei processi. + +#### Usa un sistema init + +Il livello successivo di affidabilità è quello di garantire che l'app si riavvia quando il server si riavvia. I sistemi possono ancora andare giù per una varietà di motivi. Per garantire che la tua app si riavvii in caso di crash del server, usa il sistema init integrato nel tuo sistema operativo. Il sistema di init principale oggi in uso è [systemd](https://wiki.debian.org/systemd). + +Ci sono due modi per utilizzare i sistemi init con la tua app Express: + +- Eseguire l'app in un gestore di processo e installare il gestore di processo come un servizio con il sistema init. Il gestore di processo riavvierà l'app quando l'app si blocca e il sistema init riavvierà il gestore di processo quando il sistema operativo riavvia. Questo è l'approccio raccomandato. +- Esegui la tua app (e Node) direttamente con il sistema init. Questo è un po 'più semplice, ma non si ottengono i vantaggi aggiuntivi di utilizzare un manager di processo. + +##### Systemd + +Systemd è un sistema Linux e service manager. La maggior parte delle principali distribuzioni Linux hanno adottato systemd come sistema di init predefinito. + +Un file di configurazione del servizio di sistema è chiamato _unit file_, con un nome di file che termina in `.service`. Ecco un file unità di esempio per gestire direttamente un'app Node. Sostituisci i valori racchiusi in `` per il tuo sistema e l'app: + +```sh +[Unit] +Description= + +[Service] +Type=simple +ExecStart=/usr/local/bin/node +WorkingDirectory= + +User=nobody +Group=nogroup + + +Environment=NODE_ENV=production + + +LimitNOFILE=infinity + + +LimitCORE=infinity + +StandardInput=null +StandardOutput=syslog +StandardError=syslog +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +Per ulteriori informazioni sul sistema, vedere [systemd reference (man page)](http://www.freedesktop.org/software/systemd/man/systemd.unit). + +### Esegui la tua app in un cluster + +In un sistema multi-core, è possibile aumentare le prestazioni di un'applicazione Nodo di molte volte lanciando un cluster di processi. Un cluster esegue più istanze dell'app, idealmente una istanza su ogni nucleo della CPU, distribuendo così il carico e le attività tra le istanze. + +![Bilanciamento tra istanze dell'applicazione utilizzando l'API cluster](/images/clustering.png) + +IMPORTANTE: Poiché le istanze dell'app vengono eseguite come processi separati, non condividono lo stesso spazio di memoria. Cioè, gli oggetti sono locali per ogni istanza dell'app. Pertanto, non è possibile mantenere lo stato nel codice dell'applicazione. Tuttavia, è possibile utilizzare un datastore in memoria come [Redis](http://redis.io/) per memorizzare i dati e lo stato relativi alla sessione. Questa avvertenza si applica essenzialmente a tutte le forme di ridimensionamento orizzontale, sia che si tratti di raggruppamento con più processi o più server fisici. + +Nelle applicazioni raggruppate, i processi di lavoro possono bloccarsi individualmente senza influenzare il resto dei processi. Oltre ai vantaggi delle prestazioni, l'isolamento del guasto è un altro motivo per eseguire un cluster di processi app. Ogni volta che un processo di lavoro si blocca, assicurarsi sempre di registrare l'evento e generare un nuovo processo utilizzando cluster.fork(). + +#### Uso del modulo cluster Node + +Il cluster è reso possibile con il [modulo cluster di Node](https://nodejs.org/api/cluster). Ciò consente a un processo master di generare processi di lavoro e distribuire le connessioni in entrata tra i lavoratori. + +#### Uso PM2 + +Se distribuisci la tua applicazione con PM2, puoi approfittare del clustering _without_ modificando il codice dell'applicazione. Dovresti prima assicurarti che la tua [applicazione sia senza condizione](https://pm2.keymetrics.io/docs/usage/specifics/#stateless-apps) il che significa che nessun dato locale viene memorizzato nel processo (ad esempio sessioni, connessioni websocket e simili). + +Quando si esegue un'applicazione con PM2, è possibile abilitare la modalità **cluster** per eseguirla in un cluster con un certo numero di istanze a propria scelta, come il corrispondente numero di CPU disponibili sulla macchina. È possibile modificare manualmente il numero di processi nel cluster utilizzando lo strumento da riga di comando `pm2` senza interrompere l'app. + +Per abilitare la modalità cluster, avvia la tua applicazione così: + +```bash + +$ pm2 start npm --name my-app -i 4 -- start + +$ pm2 start npm --name my-app -i max -- start +``` + +Questo può anche essere configurato all'interno di un file di processo PM2 (`ecosystem.config. s` o simile) impostando `exec_mode` su `cluster` e `instances` sul numero di lavoratori da avviare. + +Una volta in esecuzione, l'applicazione può essere ridimensionata così: + +```bash + +$ pm2 scale my-app +3 + +$ pm2 scale my-app 2 +``` + +Per ulteriori informazioni sul clustering con PM2, vedere [Modalità cluster](https://pm2.keymetrics.io/docs/usage/cluster-mode/) nella documentazione PM2. + +### Risultati richiesta cache + +Un'altra strategia per migliorare le prestazioni nella produzione è quella di nascondere il risultato delle richieste, in modo che l'app non ripeta l'operazione per servire la stessa richiesta ripetutamente. + +Usa un server di cache come [Varnish](https://www.varnish-cache.org/) o [Nginx](https://blog.nginx.org/blog/nginx-caching-guide) (vedi anche [Nginx Caching](https://serversforhackers.com/nginx-caching/)) per migliorare notevolmente la velocità e le prestazioni della tua app. + +### Usa un bilanciatore di carico + +Non importa quanto sia ottimizzata un'app, una singola istanza può gestire solo una quantità limitata di carico e traffico. Un modo per scalare un'app è quello di eseguire più istanze di esso e distribuire il traffico tramite un balancer. La configurazione di un bilanciatore di carico può migliorare le prestazioni e la velocità della tua app e permetterle di scalare più di quanto sia possibile con una singola istanza. + +Un bilanciatore di carico è di solito un proxy inverso che orchestra il traffico da e verso più istanze di applicazione e server. Puoi configurare facilmente un bilanciatore di carico per la tua app utilizzando [Nginx](https://nginx.org/en/docs/http/load_balancing) o [HAProxy](https://www.digitalocean.com/community/tutorials/an-introduction-to-haproxy-and-load-balancing-concepts). + +Con il bilanciamento del carico, potrebbe essere necessario assicurarsi che le richieste associate a un particolare ID di sessione si connettano al processo che le ha originate. Questo è conosciuto come _session affinity_, o _sticky sessions_, e può essere affrontato dal suggerimento di cui sopra per utilizzare un archivio dati come Redis per i dati di sessione (a seconda della tua applicazione). Per una discussione, vedere [Utilizzo di nodi multipli](https://socket.io/docs/v4/using-multiple-nodes/). + +### Usa un proxy inverso + +Un proxy inverso si siede davanti ad una web app ed esegue operazioni di supporto sulle richieste, oltre a dirigere le richieste verso l'app. Può gestire pagine di errore, compressione, caching, servire i file, e bilanciamento del carico tra le altre cose. + +Spostare le attività che non richiedono la conoscenza dello stato dell'applicazione per un proxy inverso libera Express per eseguire attività di applicazione specializzate. Per questo motivo, si raccomanda di eseguire Express dietro un proxy inverso come [Nginx](https://www.nginx.org/) o [HAProxy](https://www.haproxy.org/) in produzione. diff --git a/src/content/pages/it/advanced/best-practice-security.mdx b/src/content/pages/it/advanced/best-practice-security.mdx new file mode 100644 index 0000000000..1079c832bf --- /dev/null +++ b/src/content/pages/it/advanced/best-practice-security.mdx @@ -0,0 +1,276 @@ +--- +title: Migliori Pratiche Di Produzione +description: Scopri le migliori pratiche di sicurezza fondamentali per le app Express in produzione, tra cui l'utilizzo di TLS, la convalida degli input, i cookie sicuri e la prevenzione delle vulnerabilità. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Il termine *"produzione"* si riferisce allo stadio del ciclo di vita del software quando un'applicazione o API è generalmente disponibile per i suoi utenti finali o consumatori. Al contrario, nella fase di *"sviluppo"* stai ancora scrivendo attivamente e testando il codice, e l'applicazione non è aperta ad accesso esterno. Gli ambienti di sistema corrispondenti sono conosciuti rispettivamente come ambienti *production* e *development*. + +Gli ambienti di sviluppo e di produzione sono di solito impostati in modo diverso e hanno esigenze molto diverse. Che cosa bene in sviluppo potrebbe non essere accettabile nella produzione. Ad esempio, in un ambiente di sviluppo potresti voler registrare dettagliatamente gli errori per il debug, mentre lo stesso comportamento può diventare una preoccupazione di sicurezza in un ambiente di produzione. E nello sviluppo, non c'è bisogno di preoccuparsi di scalabilità, affidabilità e prestazioni, mentre queste preoccupazioni diventano fondamentali nella produzione. + + + +If you believe you have discovered a security vulnerability in Express, please see Security +Policies and Procedures. + + + +Le migliori pratiche di sicurezza per le applicazioni Express in produzione includono: + +* [Migliori Pratiche Di Produzione: Sicurezza](#production-best-practices-security) + * [Overview](#overview) + * [Non utilizzare versioni deprecate o vulnerabili di Express](#dont-use-deprecated-or-vulnerable-versions-of-express) + * [Usa TLS](#use-tls) + * [Non fidarti dell'input dell'utente](#do-not-trust-user-input) + * [Previene reindirizzamenti aperti](#prevent-open-redirects) + * [Usa Elmet](#use-helmet) + * [Riduci l'impronta digitale](#reduce-fingerprinting) + * [Usa i cookie in modo sicuro](#use-cookies-securely) + * [Non utilizzare il nome predefinito del cookie di sessione](#dont-use-the-default-session-cookie-name) + * [Imposta opzioni di sicurezza dei cookie](#set-cookie-security-options) + * [Prevenire attacchi di forza brutale contro l'autorizzazione](#prevent-brute-force-attacks-against-authorization) + * [Assicurati che le tue dipendenze siano sicure](#ensure-your-dependencies-are-secure) + * [Evitare altre vulnerabilità conosciute](#avoid-other-known-vulnerabilities) + * [Ulteriori considerazioni](#additional-considerations) + +## Non utilizzare versioni deprecate o vulnerabili di Express + +Express 2.x e 3.x non sono più mantenuti. Problemi di sicurezza e prestazioni in queste versioni non saranno risolti. Non usarli! Se non hai spostato nella versione 4, segui la [guida alla migrazione](/en/guide/migrating-4) o prendi in considerazione [Opzioni di supporto commerciale](/en/support#commercial-support-options). + +Assicurati inoltre di non utilizzare nessuna delle versioni Express vulnerabili elencate nella [pagina Aggiornamenti di sicurezza](/en/advanced/security-updates). Se lo si è, aggiornare a una delle versioni stabili, preferibilmente l'ultimo. + +## Usa TLS + +Se la tua app si occupa o trasmette dati sensibili, usa [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) per proteggere la connessione e i dati. Questa tecnologia crittografa i dati prima che vengano inviati dal client al server, impedendo così alcuni hack comuni (e facili). Anche se le richieste Ajax e POST potrebbero non essere visibilmente evidenti e sembrano "nascoste" nei browser, il loro traffico di rete è vulnerabile a [packet sniffing](https://en.wikipedia.org/wiki/Packet_analyzer) e [man-in-the-middle attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). + +Potresti avere familiarità con la crittografia Secure Socket Layer (SSL). [TLS è semplicemente la prossima progressione di SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). In altre parole, se si utilizza SSL prima, considerare l'aggiornamento a TLS. In generale, si consiglia Nginx per gestire TLS. Per un buon riferimento per configurare TLS su Nginx (e altri server), vedere [Configurazioni server consigliate (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). + +Inoltre, uno strumento utile per ottenere un certificato TLS gratuito è [Let's Encrypt](https://letsencrypt.org/about/), un gratuito, automatizzato, e autorità di certificazione aperta (CA) fornite dal [Gruppo di ricerca sulla sicurezza Internet (ISRG)](https://www.abetterinternet.org/). + +## Non fidarti dell'input utente + +Per le applicazioni web, uno dei requisiti di sicurezza più critici è la convalida e la gestione dell'input dell'utente. Questo avviene in molte forme e non li copriremo tutti qui. +In definitiva, la responsabilità di convalidare e gestire correttamente i tipi di input utente che la tua applicazione accetta è tua. + +### Impedisci reindirizzamenti aperti + +Un esempio di input utente potenzialmente pericoloso è un *open redirect*, dove un'applicazione accetta un URL come input utente (spesso nella domanda URL, ad esempio `? rl=https://esempio. om`) e utilizza `res.redirect` per impostare l'intestazione `location` e +restituisce uno stato 3xx. + +Un'applicazione deve convalidare che supporta il reindirizzamento all'URL in arrivo per evitare di inviare gli utenti a link dannosi come siti web di phishing, tra gli altri rischi. + +Ecco un esempio di controllo degli URL prima di usare `res.redirect` o `res.location`: + +```js +app.use((req, res) => { + try { + if (new Url(req. uery.url).host !== 'example.com') { + return res.status(400). nd(`Redirect non supportato all'host: ${req.query.url}`); + } + } catch (e) { + return res. tatus(400).end(`URL non valido: ${req.query.url}`); + } + res.redirect(req.query.url); +}); +``` + +## Usa Elmo + +[Helmet][helmet] può aiutare a proteggere la tua app da alcune note vulnerabilità web impostando le intestazioni HTTP in modo appropriato. + +Helmet è una funzione middleware che imposta le intestazioni di risposta HTTP legate alla sicurezza. Casco imposta le seguenti intestazioni per impostazione predefinita: + +* `Content-Security-Policy`: Una potente lista di permessi di ciò che può accadere sulla tua pagina che attenua molti attacchi +* `Cross-Origin-Opener-Policy`: aiuta a isolare la tua pagina +* `Cross-Origin-Resource-Policy`: blocca gli altri dal caricamento delle risorse cross-origin +* `Origin-Agent-Cluster`: Modifica l'isolamento del processo per essere basato sull'origine +* `Referrer-Policy`: controlla l'intestazione [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) +* `Strict-Transport-Security`: Racconta i browser per preferire HTTPS +* `X-Content-Type-Options`: Evita [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +* `X-DNS-Prefetch-Control`: controlla il prefetching DNS +* `X-D ad-Options`: Forza il salvataggio dei download (solo Internet Explorer) +* `X-Frame-Options`: intestazione legacy che attenua gli attacchi [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) +* `X-Permitted-Cross-Domain-Policies`: Controlla il comportamento cross-domain per i prodotti Adobe, come Acrobat +* `X-Powered-By`: Informazioni sul server web. Rimosso perché potrebbe essere usato in semplici attacchi +* `X-XSS-Protection`: intestazione legacy che cerca di mitigare [attacchi XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), ma peggiora le cose, quindi l'Elmo lo disabilita + +Ogni intestazione può essere configurata o disabilitata. Per saperne di più su di esso si prega di andare su [il suo sito di documentazione][helmet]. + +Installare Elmo come qualsiasi altro modulo: + +```bash +$ npm install helmet +``` + +Quindi per usarlo nel tuo codice: + +```js +// ... + +const casco = require('casco'); +app.use(casco()); + +// ... +``` + +## Riduci l'impronta digitale + +Può aiutare a fornire un ulteriore livello di sicurezza per ridurre la capacità degli aggressori di determinare +il software che un server utilizza, conosciuto come "impronta digitale". Anche se non un problema di sicurezza in sé, +ridurre la capacità di impronte digitali un'applicazione migliora la sua posizione generale di sicurezza. +Il software del server può essere improntato alle impronte digitali per quanto riguarda il modo in cui risponde a richieste specifiche, ad esempio in +le intestazioni di risposta HTTP. + +Per impostazione predefinita, Express invia l'intestazione della risposta `X-Powered-By` che puoi disabilitare +usando il metodo `app.disable()`: + +```js +app.disable('x-powered-by'); +``` + + + +Disabilitare l'intestazione `X-Powered-By ` non impedisce a un sofisticato aggressore di determinare +che un'app sta eseguendo Express. Può scoraggiare un exploit casuale, ma ci sono altri modi per +determinare che un'app è in esecuzione Express. + + + +Express invia anche i propri messaggi di risposta "404 Not Found" formattati e i messaggi di risposta di errore di formattazione +. Questi possono essere modificati da +[aggiungendo il tuo gestore non trovato](/en/starter/faq#how-do-i-handle-404-responses) +e +[scrivendo il tuo gestore di errore](/en/guide/error-handling#writing-error-handlers): + +```js +// last app.use calls right before app.listen(): + +// custom 404 +app.use((req, res, next) => { + res.status(404). end("Siamo spiacenti non riesci a trovarlo!"); +}); + +// app gestore di errori personalizzato +. se((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +## Utilizzare i cookie in modo sicuro + +Per garantire che i cookie non aprano la tua app agli exploit, non utilizzare il nome predefinito del cookie di sessione e impostare le opzioni di sicurezza dei cookie in modo appropriato. + +Ci sono due principali moduli di sessione di cookie middleware: + +* [express-session](https://www.npmjs.com/package/express-session) che sostituisce il middleware `express.session` integrato in Express 3.x. +* [cookie-session](https://www.npmjs.com/package/cookie-session) che sostituisce il middleware `express.cookieSession` integrato in Express 3.x. + +La differenza principale tra questi due moduli è come salvano i dati di sessione dei cookie. La [express-session](https://www.npmjs.com/package/express-session) middleware memorizza i dati di sessione sul server; salva solo l'ID di sessione nel cookie stesso, non i dati di sessione. Per impostazione predefinita, utilizza l'archivio in-memory e non è progettato per un ambiente di produzione. Nella produzione, dovrai impostare un archivio di sessione scalabile; vedi l'elenco di [negozi di sessione compatibili](https://github.com/expressjs/session#compatible-session-stores). + +Al contrario, [cookie-session](https://www.npmjs.com/package/cookie-session) middleware implementa la memorizzazione supportata dai cookie: serializza l'intera sessione al cookie, piuttosto che una semplice chiave di sessione. Usalo solo quando i dati di sessione sono relativamente piccoli e facilmente codificati come valori primitivi (piuttosto che oggetti). Anche se i browser dovrebbero supportare almeno 4096 byte per cookie, per assicurarsi di non superare il limite, non superare una dimensione di 4093 byte per dominio. Inoltre, essere consapevoli che i dati dei cookie saranno visibili al cliente, quindi se c'è qualche motivo per mantenerlo sicuro o oscuro, allora `express-session` potrebbe essere una scelta migliore. + +### Non utilizzare il nome predefinito del cookie di sessione + +Utilizzando il nome predefinito del cookie di sessione puoi aprire la tua app agli attacchi. Il problema di sicurezza posto è simile a `X-Powered-By`: un potenziale attaccante può usarlo per impronte digitali il server e attacchi di destinazione di conseguenza. + +Per evitare questo problema, usa i nomi generici dei cookie, ad esempio usando il middleware [express-session](https://www.npmjs.com/package/express-session): + +```js +const session = require('express-session'); +app.set('trust proxy', 1); // trust first proxy +app. se( + session({ + secret: 's3Cur3', + name: 'sessionId', + }) +); +``` + +### Imposta opzioni di sicurezza cookie + +Impostare le seguenti opzioni di cookie per migliorare la sicurezza: + +* `secure` - Assicura il browser solo invia il cookie su HTTPS. +* `httpOnly` - Assicura che il cookie venga inviato solo su HTTP(S), non su JavaScript, contribuendo a proteggere dagli attacchi di scripting cross-site. +* `domain` - indica il dominio del cookie; usalo per confrontare con il dominio del server in cui viene richiesto l'URL. Se corrispondono, controlla l'attributo percorso successivo. +* `path` - indica il percorso del cookie; usalo per confrontare con il percorso della richiesta. Se questo e dominio corrispondono, quindi inviare il cookie nella richiesta. +* `expires` - usa per impostare la data di scadenza per i cookie persistenti. + +Ecco un esempio che usa [cookie-session](https://www.npmjs.com/package/cookie-session) middleware: + +```js +const session = require('cookie-session'); +const express = require('express'); +const app = express(); + +const expiryDate = new Date(Date. ow() + 60 * 60 * 1000); // 1 ora +app. se( + session({ + name: 'session', + keys: ['key1', 'key2'], + cookie: { + secure: true, + httpOnly: true, + dominio: 'esempio. om', + percorso: 'foo/bar', + scadenza: ScadenzaData, + }, + }) +); +``` + +## Prevenire attacchi di forza brutale contro l'autorizzazione + +Assicurati che gli endpoint di accesso siano protetti per rendere i dati privati più sicuri. + +Una tecnica semplice e potente è quella di bloccare i tentativi di autorizzazione utilizzando due metriche: + +1. Il numero di tentativi consecutivi falliti dallo stesso nome utente e indirizzo IP. +2. Il numero di tentativi falliti da un indirizzo IP per un lungo periodo di tempo. Ad esempio, blocca un indirizzo IP se fa 100 tentativi falliti in un giorno. + +Il pacchetto [rate-limiter-flexible](https://github.com/animir/node-rate-limiter-flexible) fornisce strumenti per rendere questa tecnica facile e veloce. Puoi trovare [un esempio di protezione della forza brutale nella documentazione](https://github.com/animir/node-rate-limiter-flexible/wiki/Overall-example#login-endpoint-protection) + +## Assicurati che le tue dipendenze siano sicure + +Usare npm per gestire le dipendenze della tua applicazione è potente e conveniente. Ma i pacchetti che si utilizzano possono contenere vulnerabilità di sicurezza critiche che potrebbero influenzare anche la vostra applicazione. La sicurezza della tua app è forte solo come il "link più debole" nelle tue dipendenze. + +Dal momento che npm@6, npm esamina automaticamente ogni richiesta di installazione. Inoltre, puoi usare `npm audit` per analizzare il tuo albero delle dipendenze. + +```bash +$ npm audit +``` + +Se vuoi rimanere più sicuro, considera [Snyk](https://snyk.io/). + +Snyk offre sia un [strumento da riga di comando](https://www.npmjs.com/package/snyk) che una [integrazione Github](https://snyk.io/docs/github) che controlla la tua applicazione contro [database di vulnerabilità open source di Snyk](https://snyk.io/vuln/) per qualsiasi vulnerabilità nota nelle tue dipendenze. Installare il CLI come segue: + +```bash +$ npm install -g snyk +$ cd your-app +``` + +Usa questo comando per testare la tua applicazione per le vulnerabilità: + +```bash +$ snyk test +``` + +### Evitare altre vulnerabilità note + +Tieni d'occhio [Progetto di Sicurezza Nodi](https://npmjs.com/advisories) o [Snyk](https://snyk.io/vuln/) gli avvisi che possono influenzare Express o altri moduli che la tua app utilizza. In generale, queste banche dati sono risorse eccellenti per la conoscenza e gli strumenti sulla sicurezza del nodo. + +Infine, Express apps—come qualsiasi altra web app—può essere vulnerabile a una varietà di attacchi basati sul web. Conoscere se stessi con conosciute [vulnerabilità web](https://www.owasp.org/www-project-top-ten/) e prendere precauzioni per evitarli. + +## Considerazioni aggiuntive + +Ecco alcuni ulteriori consigli dall'eccellente [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/). Fare riferimento a quel post del blog per tutti i dettagli su queste raccomandazioni: + +* Filtrare e sanificare sempre l'input dell'utente per proteggere contro gli script cross-site (XSS) e gli attacchi di iniezione dei comandi. +* Difendi gli attacchi di SQL injection utilizzando query parametrizzate o dichiarazioni preparate. +* Usa lo strumento open-source [sqlmap](http://sqlmap.org/) per rilevare le vulnerabilità di SQL injection nella tua app. +* Usa gli strumenti [nmap](https://nmap.org/) e [sslyze](https://github.com/nabla-c0d3/sslyze) per testare la configurazione dei tuoi cifrari SSL, chiavi, rinegoziazione e validità del certificato. +* Usa [safe-regex](https://www.npmjs.com/package/safe-regex) per garantire che le tue espressioni regolari non siano suscettibili di [espressione regolare negazione del servizio](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) attacchi. + +[helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/it/advanced/healthcheck-graceful-shutdown.md b/src/content/pages/it/advanced/healthcheck-graceful-shutdown.md new file mode 100644 index 0000000000..580db6bbdf --- /dev/null +++ b/src/content/pages/it/advanced/healthcheck-graceful-shutdown.md @@ -0,0 +1,28 @@ +--- +title: Controlli sanitari e spegnimento grazioso +description: Scopri come implementare controlli di salute e arresto aggraziato nelle app Express per migliorare l'affidabilità, gestire le distribuzioni e integrare con bilanciatori di carico come Kubernetes. +--- + +## Spegnimento grazioso + +Quando si distribuisce una nuova versione della propria applicazione, è necessario sostituire la versione precedente. Il gestore di processo che stai utilizzando invierà prima un segnale SIGTERM all'applicazione per notificarlo che verrà ucciso. Una volta che l'applicazione ottiene questo segnale, dovrebbe smettere di accettare nuove richieste, completare tutte le richieste in corso, pulire le risorse utilizzate, incluse le connessioni del database e i blocchi di file quindi uscire. + +### Esempio + +```js +const server = app.listen(port); + +process.on('SIGTERM', () => { + debug('SIGTERM signal received: closing HTTP server'); + server.close(() => { + debug('HTTP server closed'); + }); +}); +``` + +## Controlli sanitari + +Un bilanciatore del carico utilizza controlli sanitari per determinare se un'istanza di applicazione è sana e può accettare le richieste. Ad esempio, [Kubernetes ha due controlli di salute](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/): + +- `liveness`, che determina quando riavviare un contenitore. +- `pronte`, che determina quando un contenitore è pronto per iniziare ad accettare il traffico. Quando un baccello non è pronto, viene rimosso dai balanceri di carico di servizio. diff --git a/src/content/pages/it/advanced/security-updates.mdx b/src/content/pages/it/advanced/security-updates.mdx new file mode 100644 index 0000000000..4e11a95ed0 --- /dev/null +++ b/src/content/pages/it/advanced/security-updates.mdx @@ -0,0 +1,87 @@ +--- +title: Aggiornamenti di sicurezza +description: Rivedere gli ultimi aggiornamenti e patch di sicurezza per Express.js, tra cui elenchi di vulnerabilità dettagliati per diverse versioni per aiutare a mantenere un'applicazione sicura. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Le vulnerabilità di Node.js influenzano direttamente Express. Pertanto, tieni un orologio su Node.js +vulnerabilità e assicurati di utilizzare l'ultima versione stabile +di Node.js. + + + +L'elenco di seguito elenca le vulnerabilità Express che sono state risolte nell'aggiornamento della versione specificata. + + + +If you believe you have discovered a security vulnerability in Express, please see Security +Policies and Procedures. + + + +## 4.x + +* 4.21.2 + * La dipendenza `path-to-regexp` è stata aggiornata per affrontare una [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +* 4.21.1 + * Il `cookie` di dipendenza è stato aggiornato per indirizzare un [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), Questo può influenzare la tua applicazione se usi `res.cookie`. +* 4.20.0 + * Corretta vulnerabilità XSS in `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + * La dipendenza `serve-static` è stata aggiornata per affrontare una [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). + * La dipendenza `send` è stata aggiornata per indirizzare una [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + * La dipendenza `path-to-regexp` è stata aggiornata per affrontare una [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + * La dipendenza `body-parser` è stata aggiornata per aggiungere una [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), Questo può influenzare la tua applicazione se l'url è stato attivato . +* 4.19.0, 4.19.1 + * Risolto la vulnerabilità di reindirizzamento aperto in `res.location` e `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +* 4.17.3 + * La dipendenza `qs` è stata aggiornata per indirizzare una [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). Questo può influenzare la tua applicazione se vengono utilizzate le seguenti API: `req.query`, `req.body`, `req.param`. +* 4.16.0 + * La dipendenza `inoltrata` è stata aggiornata per indirizzare una [vulnerability](https://npmjs.com/advisories/527). Questo può influenzare la tua applicazione se vengono utilizzate le seguenti API: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + * La dipendenza `mime` è stata aggiornata per affrontare una [vulnerability](https://npmjs.com/advisories/535), ma questo problema non influisce su Express. + * La dipendenza `send` è stata aggiornata per fornire una protezione contro una [vulnerabilità Node.js 8.5.0](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). Questo influenza solo l'esecuzione di Express sulla specifica versione di Node.js 8.5.0. +* 4.15.5 + * Il `debug` della dipendenza è stato aggiornato per affrontare una [vulnerability](https://snyk.io/vuln/npm:debug:20170905), ma questo problema non influisce su Express. + * La dipendenza `fresh` è stata aggiornata per affrontare una [vulnerability](https://npmjs.com/advisories/526). Questo influenzerà la tua applicazione se vengono utilizzate le seguenti API: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. +* 4.15.3 + * Il `ms` di dipendenza è stato aggiornato per indirizzare un [vulnerability](https://snyk.io/vuln/npm:ms:20170412). Questo può influenzare la tua applicazione se l'input di stringa non attendibile viene passato all'opzione `maxAge` nelle seguenti API: `express.static`, `res.sendfile`, e `res.sendFile`. +* 4.15.2 + * La dipendenza `qs` è stata aggiornata per affrontare una [vulnerability](https://snyk.io/vuln/npm:qs:20170213), ma questo problema non influisce su Express. Aggiornare al 4.15.2 è una buona pratica, ma non è necessario per affrontare la vulnerabilità. +* 4.11.1 + * Risolto la vulnerabilità alla divulgazione del percorso di root in `express.static`, `res.sendfile`, e `res.sendFile` +* 4.10.7 + * Risolto la vulnerabilità di reindirizzamento aperto in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 4.8.8 + * Vulnerabilità delle directory corrette in `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +* 4.8.4 + * Node.js 0.10 può perdere `fd`s in alcune situazioni che influenzano `express.static` e `res.sendfile`. Le richieste dannose potrebbero causare perdite di `fd`s e alla fine portare a errori `EMFILE` e il server non reattività. +* 4.8.0 + * Gli array sparsi che hanno indici estremamente alti nella stringa di interrogazione potrebbero causare il processo di esaurimento della memoria e crash del server. + * Oggetti di stringa di query estremamente annidati potrebbero causare il blocco del processo e rendere il server non reattivo temporaneamente. + +## 3.x + + +**Express 3.x È END-OF-LIFE E NON È MANTENENTE LONGERI** + +I problemi noti e sconosciuti di sicurezza e prestazioni in 3.x non sono stati affrontati dall'ultimo aggiornamento (1 agosto 2015). Si consiglia vivamente di utilizzare l'ultima versione di Express. + +Se non sei in grado di aggiornare il precedente 3.x, ti preghiamo di considerare [Opzioni di Supporto Commerciale](/en/support#commercial-support-options). + + + +* 3.19.1 + * Risolto la vulnerabilità alla divulgazione del percorso di root in `express.static`, `res.sendfile`, e `res.sendFile` +* 3.19.0 + * Risolto la vulnerabilità di reindirizzamento aperto in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 3.16.10 + * Vulnerabilità delle directory corrette in `express.static`. +* 3.16.6 + * Node.js 0.10 può perdere `fd`s in alcune situazioni che influenzano `express.static` e `res.sendfile`. Le richieste dannose potrebbero causare perdite di `fd`s e alla fine portare a errori `EMFILE` e il server non reattività. +* 3.16.0 + * Gli array sparsi che hanno indici estremamente alti nella stringa di query potrebbero causare il processo di esaurimento della memoria e crash del server. + * Oggetti di stringa di query estremamente annidati potrebbero causare il blocco del processo e rendere il server non reattivo temporaneamente. +* 3.3.0 + * La risposta 404 di un tentativo di override metodo non supportato era suscettibile di attacchi di scripting cross-site. diff --git a/src/content/pages/it/guide/database-integration.mdx b/src/content/pages/it/guide/database-integration.mdx new file mode 100644 index 0000000000..887cbcfe0a --- /dev/null +++ b/src/content/pages/it/guide/database-integration.mdx @@ -0,0 +1,503 @@ +--- +title: Integrazione database +description: Scopri come integrare vari database con le applicazioni Express.js, inclusi esempi di configurazione per MongoDB, MySQL, PostgreSQL e altro ancora. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Aggiungere la possibilità di collegare i database alle applicazioni Express è solo una questione di caricare un driver Node.js appropriato per il database nella tua app. Questo documento spiega brevemente come aggiungere e utilizzare alcuni dei moduli Node.js più popolari per i sistemi di database nell'app Express: + +* [Cassandra](#cassandra) +* [Couchbase](#couchbase) +* [CouchDB](#couchdb) +* [LevelDB](#leveldb) +* [MySQL](#mysql) +* [MongoDB](#mongodb) +* [Neo4j](#neo4j) +* [Oracle](#oracle) +* [PostgreSQL](#postgresql) +* [Redis](#redis) +* [SQL Server](#sql-server) +* [SQLite](#sqlite) +* [Elasticsearch](#elasticsearch) + + + +Questi driver di database sono tra molti che sono disponibili. Per altre opzioni, cerca sul sito +[npm](https://www.npmjs.com/). + + + +## Cassandra + +**Modulo**: [cassandra-driver](https://github.com/datastax/nodejs-driver) + +### Installazione + +```bash +$ npm install cassandra-driver +``` + +### Esempio + +```js +const cassandra = require('cassandra-driver'); +const client = new cassandra.Client({ contactPoints: ['localhost'] }); + +client. xecute('select key from system.local', (err, result) => { + if (err) throw err; + console.log(result.rows[0]); +}); +``` + +## Couchbase + +**Modulo**: [couchnode](https://github.com/couchbase/couchnode) + +### Installazione + +```bash +$ npm install couchbase +``` + +### Esempio + +```js +const couchbase = require('couchbase'); +const bucket = new couchbase.Cluster('http://localhost:8091').openBucket('bucketName'); + +// aggiungi un documento a un bucket +. nsert('document-key', { name: 'Matt', shoeSize: 13 }, (err, result) => { + if (err) { + console. og(err); + } else { + console. og(result); + } +}); + +// ottieni tutti i documenti con scarpa taglia 13 +const n1ql = 'SELECT d. FROM `bucketName` d WHERE shoeSize = $1'; +const query = N1qlQuery. romString(n1ql); +bucket.query(query, [13], (err, result) => { + if (err) { + console. og(err); + } else { + console.log(result); + } +}); +``` + +## CouchDB + +**Modulo**: [nano](https://github.com/dscape/nano) + +### Installazione + +```bash +$ npm install nano +``` + +### Esempio + +```js +const nano = require('nano')('http://localhost:5984'); +nano.db.create('books'); +const books = nano.db. se('books'); + +// Inserisci un documento di libro nel database di libri +. nsert({ name: 'The Art of war' }, null, (err, body) => { + if (err) { + console. og(err); + } else { + console. og(body); + } +}); + +// Ottieni un elenco di tutti i libri +libri. ist((err, body) => { + if (err) { + console. og(err); + } else { + console.log(body.rows); + } +}); +``` + +## LevelDB + +**Modulo**: [levelup](https://github.com/rvagg/node-levelup) + +### Installazione + +```bash +$ npm install level levelup down +``` + +### Esempio + +```js +const levelup = require('levelup'); +const db = levelup('./mydb'); + +db. ut('name', 'LevelUP', (err) => { + if (err) return console.log('Ooops!', err); + + db. et('name', (err, value) => { + if (err) return console. og('Ooops!', err); + + console.log(`name=${value}`); + }); +}); +``` + +## MySQL + +**Modulo**: [mysql](https://github.com/felixge/node-mysql/) + +### Installazione + +```bash +$ npm install mysql +``` + +### Esempio + +```js +const mysql = require('mysql'); +const connection = mysql. reateConnection({ + host: 'localhost', + user: 'dbuser', + password: 's3kreee7', + database: 'my_db', +}); + +connessione. onnect(); + +connection.query('SELECT 1 + 1 AS solution', (err, rows, fields) => { + if (err) throw err; + + console. og('La soluzione è: ', righe[0].solution); +}); + +connessione.end(); +``` + +## MongoDB + +**Modulo**: [mongodb](https://github.com/mongodb/node-mongodb-native) + +### Installazione + +```bash +$ npm install mongodb +``` + +### Esempio (v2.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { + if (err) throw err; + + db. ollection('mammals') + .find() + . oArray((err, result) => { + if (err) throw err; + + console. og(risultato); + }); +}); +``` + +### Esempio (v3.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, client) => { + if (err) throw err; + + const db = client. b('animals'); + + db.collection('mammals') + .find() + . oArray((err, result) => { + if (err) throw err; + + console. og(risultato); + }); +}); +``` + +Se vuoi un driver modello oggetto per MongoDB, guarda [Mongoose](https://github.com/LearnBoost/mongoose). + +## Neo4j + +**Modulo**: [neo4j-driver](https://github.com/neo4j/neo4j-javascript-driver) + +### Installazione + +```bash +$ npm install neo4j-driver +``` + +### Esempio + +```js +const neo4j = require('neo4j-driver'); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth. asic('neo4j', 'letmein')); + +const session = driver.session(); + +session.readTransaction((tx) => { + return tx + . un('MATCH (n) RETURN count(n) AS count') + .then((res) => { + console.log(res.records[0]. et('count')); + }) + .catch((error) => { + console. og(errore); + }); +}); +``` + +## Oracle + +**Modulo**: [oracledb](https://github.com/oracle/node-oracledb) + +### Installazione + +NOTA: [Vedi i prerequisiti di installazione](https://github.com/oracle/node-oracledb#-installation). + +```bash +$ npm install oracledb +``` + +### Esempio + +```js +const oracledb = require('oracledb'); +const config = { + utente: '', + password: '', + connectString: 'localhost:1521/orcl', +}; + +async function getEmployee(empId) { + let conn; + + try { + conn = await oracledb. etConnection(config); + + const result = await conn. xecute('select * from employees where employee_id = :id', [empId]); + + console. og(result.rows[0]); + } catch (err) { + console. og('Ouch! , err); + } finalmente { + if (conn) { + // conn assignment worked, bisogno di chiudere + attesa conn. lose(); + } + } +} + +getEmployee(101); +``` + +## PostgreSQL + +**Modulo**: [pg-promise](https://github.com/vitaly-t/pg-promise) + +### Installazione + +```bash +$ npm install pg-promise +``` + +### Esempio + +```js +const pgp = require('pg-promise')(/* options */); +const db = pgp('postgres://username:password@host:port/database'); + +db.one('SELECT $1 AS value', 123) + . hen((data) => { + console.log('DATA:', data.value); + }) + . atch((error) => { + console.log('ERROR:', error); +}); +``` + +## Redis + +**Modulo**: [redis](https://github.com/mranney/node_redis) + +### Installazione + +```bash +$ npm install redis +``` + +### Esempio + +```js +const redis = require('redis'); +const client = redis.createClient(); + +client.on('error', (err) => { + console.log(`Error ${err}`); +}); + +client. et('string key', 'string val', redis.print); +client.hset('hash key', 'hashtest 1', 'some value', redis.print); +client. set(['hash key', 'hashtest 2', 'some other value'], redis.print); + +client. keys('hash key', (err, replies) => { + console.log(`${replies.length} risponde:`); + + risposte. orEach((reply, i) => { + console. og(` ${i}: ${reply}`); + }); + + client.quit(); +}); +``` + +## Server SQL + +**Modulo**: [tedious](https://github.com/tediousjs/tedious) + +### Installazione + +```bash +$ npm install tedious +``` + +### Esempio + +```js +const Connection = require('tedious').Connection; +const Request = require('tedious'). ricerca; + +const config = { + server: 'localhost', + authentication: { + type: 'default', + options: { + userName: 'your_username', // aggiorna la password + : 'tuo_password', // aggiornami + }, + }, +}; + +const connection = new Connection(config); + +connessione. n('connect', (err) => { + if (err) { + console. og(err); + } else { + executeStatement(); + } +}); + +function executeStatement() { + request = new Request("select 123, 'hello world'", (err, rowCount) => { + if (err) { + console. og(err); + } else { + console. og(`${rowCount} righe`); + } + connessione. lose(); + }); + + request.on('row', (columns) => { + colonne. orEach((column) => { + if (column.value === null) { + console. og('NULL'); + } else { + console.log(column. alue); + } + }); + }); + + connessione.execSql(request); +} +``` + +## SQLite + +**Modulo**: [sqlite3](https://github.com/mapbox/node-sqlite3) + +### Installazione + +```bash +$ npm install sqlite3 +``` + +### Esempio + +```js +const sqlite3 = require('sqlite3').verbose(); +const db = new sqlite3.Database(':memory:'); + +db.serialize(() => { + db. un('CREATE TABLE lorem (info TEXT)'); + const stmt = db. repare('INSERT INTO lorem VALUES (?)'); + + for (let i = 0; i < 10; i++) { + stmt. un(`Ipsum ${i}`); + } + + stmt.finalize(); + + db. ach('SELECT rowid AS id, info FROM lorem', (err, row) => { + console. og(`${row.id}: ${row.info}`); + }); +}); + +db.close(); +``` + +## Elasticsearch + +**Modulo**: [elasticsearch](https://github.com/elastic/elasticsearch-js) + +### Installazione + +```bash +$ npm install elasticsearch +``` + +### Esempio + +```js +const elasticsearch = require('elasticsearch'); +const client = elasticsearch.Client({ + host: 'localhost:9200', +}); + +client + . earch({ + index: 'books', + type: 'book', + body: { + query: { + multi_match: { + query: 'express js', + campi: ['title', 'description'], + }, + }, + }, + }) + . hen( + (response) => { + const hits = response.hits. its; + }, + (error) => { + console. gara(error.message); + } +); +``` diff --git a/src/content/pages/it/guide/migrating-4.mdx b/src/content/pages/it/guide/migrating-4.mdx new file mode 100644 index 0000000000..93d4d13e8f --- /dev/null +++ b/src/content/pages/it/guide/migrating-4.mdx @@ -0,0 +1,662 @@ +--- +title: Passaggio a Express 4 +description: Una guida per la migrazione delle applicazioni Express.js dalla versione 3 alla 4, che copre i cambiamenti nel middleware, nel routing, e come aggiornare il codice in modo efficace. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express 4 è un cambiamento di rottura rispetto a Express 3. Ciò significa che un'app Express 3 esistente non funzionerà_ se aggiorni la versione Express nelle sue dipendenze. + +Questo articolo comprende: + + + +## Modifiche in Express 4 + +Nel documento Express 4 sono stati apportati diversi cambiamenti significativi: + + + +Cfr. anche: + +* [Nuove funzionalità in 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +* [Migrazione da 3.x a 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) + +### Modifiche al sistema Express core e middleware + +Express 4 non dipende più da Connect, e rimuove tutti i middleware +incorporati dal suo core, ad eccezione della funzione `express.static`. Ciò significa che +Express è ora un routing indipendente e un framework web middleware, e il versionamento e le versioni di +Express non sono influenzati dagli aggiornamenti di middleware. + +Senza middleware integrato, è necessario aggiungere esplicitamente tutto il middleware +che è necessario per eseguire l'app. Basta seguire questi passaggi: + +1. Installa il modulo: `npm install --save ` +2. Nella tua app, richiede il modulo: `require('module-name')` +3. Usa il modulo in base alla sua documentazione: `app.use( ... )` + +La seguente tabella elenca il middleware Express 3 e le loro controparti in Express 4. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Express 3Express 4
+ express.bodyParser + + body-parser + + multer +
+ express.compress + + Compressione +
+ express.cookieSession + + cookie-session +
+ express.cookieParser + + cookie-parser +
+ express.logger + + morgan +
+ express.session + + express-session +
+ express.favicon + + serve-favicon +
+ express.responseTime + + tempo di risposta +
+ express.errorHandler + + errorhandler +
+ express.methodOverride + + method-override +
+ express.timeout + + connect-timeout +
+ express.vhost + + vhost +
+ express.csrf + + csurf +
+ express.directory + + serve-index +
+ express.static + + servo-statico +
+ +Ecco la [lista completa](https://github.com/senchalabs/connect#middleware) di Express 4 middleware. + +Nella maggior parte dei casi, puoi semplicemente sostituire la vecchia versione 3 middleware con +la sua controparte Express 4. Per i dettagli, vedere la documentazione del modulo in +GitHub. + +#### `app.use` accetta parametri + +Nella versione 4 è possibile utilizzare un parametro variabile per definire il percorso in cui vengono caricate le funzioni middleware, quindi leggere il valore del parametro dal gestore del percorso. +Per esempio: + +```js +app.use('/book/:id', (req, res, next) => { + console.log('ID:', req.params.id); + next(); +}); +``` + +### Il sistema di routing + +Le app ora caricano implicitamente il middleware di routing, quindi non devi più preoccuparti di +dell'ordine in cui il middleware viene caricato rispetto a +il middleware `router`. + +Il modo in cui definisci i percorsi non è cambiato, ma il sistema di routing ha due +nuove funzionalità per aiutare a organizzare i tuoi percorsi: + +* Un nuovo metodo, `app.route()`, per creare i gestori di rotte per un percorso tracciato. +* Una nuova classe, `express.Router`, per creare percorsi modulari montabili. + +#### `app.route()` metodo + +Il nuovo metodo `app.route()` ti permette di creare i gestori di rotte +per un percorso percorso. Poiché il percorso è specificato in una singola posizione, è utile creare percorsi modulari, così come ridurre la ridondanza e pneumatici. Per ulteriori informazioni +sulle rotte, vedere [`Router()` documentazione](/en/4x/api#router). + +Ecco un esempio di router incatenati che sono definiti utilizzando la funzione `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res. end('Ottieni un libro casuale'); + }) + . ost((req, res) => { + res.send('Add a book'); + }) + . ut((req, res) => { + res.send('Aggiorna il libro'); +}); +``` + +#### Classe `express.Router` + +L'altra funzione che aiuta a organizzare i percorsi è una nuova classe, +`express.Router`, che puoi usare per creare percorsi modulari montabili +. Un'istanza `Router` è un sistema completo di routing middleware e +; per questo motivo è spesso chiamata "mini-app". + +L'esempio seguente crea un router come modulo, carica middleware in +, definisce alcuni percorsi e lo monta su un percorso sull'app principale. + +Ad esempio, crea un file router chiamato `birds.js` nella directory app, +con i seguenti contenuti: + +```js +var express = require('express'); +var router = express.Router(); + +// middleware specifico per questo router +router. se((req, res, next) => { + console.log('Time: ', Date. ow()); + next(); +}); +// definire il router della home page +. et('/', (req, res) => { + res.send('Birds home page'); +}); +// definire il router circa il percorso +. et('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Quindi, caricare il modulo router nell'app: + +```js +var birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +L'app sarà ora in grado di gestire le richieste ai percorsi `/birds` e +`/birds/about`, e chiamerà il middleware `timeLog` +che è specifico per il percorso. + +### Altre modifiche + +La seguente tabella elenca altre modifiche di piccole dimensioni ma importanti in Express 4: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
OggettoDescrizione
Node.jsExpress 4 richiede Node.js 0.10.x o versioni successive e ha abbandonato il supporto per Node.js 0.8.x.
`http.createServer()` + Il modulo `http` non è più necessario, a meno che non sia necessario lavorare direttamente con esso + (socket.io/SPDY/HTTPS). L'app può essere avviata utilizzando la funzione `app.listen()`. +
`app.configure()` + La funzione `app.configure()` è stata rimossa. Usa la funzione `process.env.NODE_ENV` o + `app.get('env')` per rilevare l'ambiente e configurare l'app di conseguenza. +
`json spaces` + La proprietà dell'applicazione `json spaces` è disabilitata per impostazione predefinita in Express 4. +
`req.accepted()` + Usa `req.accepts()`, `req.acceptsEncodings()`, `req.acceptsCharsets()`, and + `req.acceptsLanguages()`. +
`res.location()`Non risolve più gli URL relativi.
`req.params`È stato un array; ora un oggetto.
`res.locals`Era una funzione; ora un oggetto.
`res.headerSent`Cambiato in `res.headersSent`.
`app.route`Ora disponibile come `app.mountpath`.
`res.on('header')`rimosso.
`res.charset`rimosso.
`res.setHeader('Set-Cookie', val)` + La funzionalità è ora limitata all'impostazione del valore di base dei cookie. Usa `res.cookie()` per le funzionalità + aggiunte. +
+ +## Migrazione ad esempio app + +Ecco un esempio di migrazione di un'applicazione Express 3 per Express 4. +I file di interesse sono `app.js` e `package.json`. + +### Versione 3 app + +#### `app.js` + +Considera un'applicazione Express v.3 con il seguente file `app.js`: + +```js +var express = require('express'); +var route = require('./routes'); +var user = require('. routes/user'); +var http = require('http'); +var path = require('path'); + +var app = express(); + +// tutti gli ambienti +app. et('port', process.env.PORT 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(express.favicon()); +app.use(express.logger('dev')); +app.use(express.methodOverride()); +app.use(express. ession({ secret: 'your secret here' })); +app.use(express.bodyParser()); +app.use(app.router); +app.use(express. tatic(path.join(__dirname, 'public'))); + +// sviluppo solo +if (app.get('env') === 'development') { + app. se(express.errorHandler()); +} + +app.get('/', routes.index); +app.get('/users', user.list); + +http. reateServer(app).listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + +#### `package.json` + +Il file `package.json` che accompagna la versione 3 potrebbe sembrare +qualcosa del genere: + +```json +{ + "name": "application-name", + "version": "0.0. ", + "private": true, + "scripts": { + "start": "node app. s" + }, + "dependencies": { + "express": "3. 2.0", + "pug": "*" + } +} +``` + +### Processo + +Inizia il processo di migrazione installando il middleware richiesto per l'app +Express 4 e aggiornando Express e Pug alla rispettiva versione +con il seguente comando: + +```bash +$ npm install serve-favicon morgan method-override express-session body-parser multer errorhandler express@latest pug@latest --save +``` + +Effettuare le seguenti modifiche a `app.js`: + +1. Le funzioni integrate di Express middleware `express.favicon`, + `express.logger`, `express.methodOverride`, + `express.session`, `express.bodyParser` e + `express.errorHandler` non sono più disponibili nell'oggetto `express` + . Devi installare manualmente le loro alternative + e caricarle nell'app. + +2. Non è più necessario caricare la funzione `app.router`. + Non è un valido oggetto app Express 4, quindi rimuovi il codice + `app.use(app.router);`. + +3. Assicurati che le funzioni middleware siano caricate nell'ordine corretto: carica `errorHandler` dopo aver caricato le rotte dell'app. + +### Versione 4 app + +#### `package.json` + +L'esecuzione del comando `npm` sopra aggiornerà `package.json` come segue: + +```json +{ + "name": "application-name", + "version": "0.0. ", + "private": true, + "scripts": { + "start": "node app. s" + }, + "dependencies": { + "body-parser": "^1.5.2", + "errorhandler": "^1.1. ", + "express": "^4.8.0", + "express-session": "^1. .2", + "pug": "^2.0.0", + "method-override": "^2. .2", + "morgan": "^1.2.2", + "multer": "^0.1. ", + "serve-favicon": "^2.0.1" + } +} +``` + +#### `app.js` + +Quindi, rimuovere il codice non valido, caricare il middleware richiesto e fare altre modifiche +se necessario. Il file `app.js` sarà simile a questo: + +```js +var http = require('http'); +var express = require('express'); +var route = require('./routes'); +var user = require('. routes/user'); +var path = require('path'); + +var favicon = require('serve-favicon'); +var logger = require('morgan'); +var methodOverride = require('method-override'); +var session = require('express-session'); +var bodyParser = require('body-parser'); +var multer = require('multer'); +var errorHandler = require('errorhandler'); + +var app = express(); + +// tutti gli ambienti +app. et('port', process.env.PORT 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(favicon(path.join(__dirname, '/public/favicon.ico')); +app.use(logger('dev')); +app. se(methodOverride()); +app. se( + session({ + resave: true, + saveUninitialized: true, + segreto: 'uwotm8', + }) +); +app. se(bodyParser.json()); +app.use(bodyParser.urlencoded({ extened: true })); +app.use(multer()); +app.use(express.static(path.join(__dirname, 'public'))); + +app.get('/', routes. ndex); +app.get('/users', user.list); + +// la gestione degli errori middleware dovrebbe essere caricata dopo il caricamento delle rotte +se (app. et('env') === 'development') { + app. se(errorHandler()); +} + +var server = http.createServer(app); +server.listen(app. et('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + + +A meno che non sia necessario lavorare direttamente con il modulo `http` (socket.io/SPDY/HTTPS), il caricamento non è richiesto e l'applicazione può essere semplicemente avviata in questo modo: + +```js +app.listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + + + +### Esegui l'app + +Il processo di migrazione è completo, e l'app è ora un'app +Express 4. Per confermare, avviare l'applicazione utilizzando il seguente comando: + +```bash +$ node . +``` + +Carica [http://localhost:3000](http://localhost:3000) +e vedi che la home page è resa da Express 4. + +## Aggiornamento al generatore di app Express 4 + +The command-line tool to generate an Express app is still +`express`, but to upgrade to the new version, you must uninstall +the Express 3 app generator and then install the new +`express-generator`. + +### Installazione + +Se hai già installato il generatore di app Express 3 sul tuo sistema, +devi disinstallarlo: + +```bash +$ npm uninstall -g express +``` + +A seconda di come i privilegi di file e directory sono configurati, +potrebbe essere necessario eseguire questo comando con `sudo`. + +Ora installa il nuovo generatore: + +```bash +$ npm install -g express-generator +``` + +A seconda di come i privilegi di file e directory sono configurati, +potrebbe essere necessario eseguire questo comando con `sudo`. + +Ora il comando `express` sul tuo sistema viene aggiornato al generatore +Express 4. + +### Modifiche al generatore di app + +Le opzioni di comando e l'uso restano in gran parte uguali, con le seguenti eccezioni: + +* Rimosso l'opzione `--sessions`. +* Rimosso l'opzione `--jshtml`. +* Aggiunta l'opzione `--hogan` per supportare [Hogan.js](http://twitter.github.io/hogan.js/). + +### Esempio + +Esegue il seguente comando per creare un'app Express 4: + +```bash +$ express app4 +``` + +Se si guarda il contenuto del file `app4/app.js`, si noterà +che tutte le funzioni middleware (tranne `express. tatic`) che sono richiesti per +l'applicazione sono caricati come moduli indipendenti, e il 'router' middleware +non è più esplicitamente caricato nell'app. + +Noterai anche che il file `app.js` è ora un Node. s modulo, in contrasto con l'app standalone che è stata generata dal vecchio generatore. + +Dopo aver installato le dipendenze, avviare l'applicazione utilizzando il seguente comando: + +```bash +$ npm start +``` + +Se guardi lo script `npm start` nel `package. file son`, +noterai che il comando attuale che avvia l'app è +`node . bin/www`, che era `node app.js` +in Express 3. + +Poiché il file `app.js` generato dal generatore di Express 4 +è ora un Node. s modulo, non può più essere avviato indipendentemente come app +(a meno che tu non modifichi il codice). Il modulo deve essere caricato in un file Node.js +e avviato tramite il file Node.js. Il file Node.js è `./bin/www` +in questo caso. + +Né la directory `bin` né il file `www` +extensionless sono obbligatori per creare un'app Express o per avviare l'app. Sono +solo suggerimenti fatti dal generatore, quindi sentitevi liberi di modificarli per soddisfare le vostre esigenze +. + +To get rid of the `www` directory and keep things the "Express 3 way", +delete the line that says `module.exports = app;` at the end of the +`app.js` file, then paste the following code in its place: + +```js +app.set('port', process.env.PORT 3000); + +var server = app.listen(app.get('port'), () => { + debug('Express server listening on port ' + server.address().port); +}); +``` + +Assicurati di caricare il modulo `debug` nella parte superiore del file `app.js` utilizzando il seguente codice: + +```js +var debug = require('debug')('app4'); +``` + +Successivamente, cambia `"start": "node ./bin/www"` nel file `package.json` in `"start": "node app.js"`. + +Ora hai spostato la funzionalità di `./bin/www` di nuovo in +`app.js`. Questo cambiamento non è raccomandato, ma l'esercizio ti aiuta +a capire come `. bin/www` funziona e perché il file `app.js` +non inizia più da solo. diff --git a/src/content/pages/it/guide/migrating-5.mdx b/src/content/pages/it/guide/migrating-5.mdx new file mode 100644 index 0000000000..8dc4a60c8e --- /dev/null +++ b/src/content/pages/it/guide/migrating-5.mdx @@ -0,0 +1,678 @@ +--- +title: Passaggio a Express 5 +description: Una guida completa per la migrazione delle applicazioni Express.js dalla versione 4 alla 5, che descrive in dettaglio i cambiamenti di rottura, i metodi deprecati e i nuovi miglioramenti. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express 5 non è molto diverso da Express 4; anche se mantiene la stessa API di base, ci sono ancora cambiamenti che rompono la compatibilità con la versione precedente. Pertanto, un'applicazione costruita con Express 4 potrebbe non funzionare se lo si aggiorna per utilizzare Express 5. + +Per installare questa versione, è necessario avere una versione 18 o superiore. Quindi, esegui il seguente comando nella directory dell'applicazione: + +```sh +npm install "express@5" +``` + +È quindi possibile eseguire i test automatici per vedere cosa non funziona, e risolvere i problemi in base agli aggiornamenti elencati di seguito. Dopo aver affrontato i fallimenti di test, eseguire l'app per vedere quali errori si verificano. Scoprirai subito se l'app utilizza metodi o proprietà che non sono supportati. + +## Express 5 Codemods + +Per aiutarti a migrare il tuo server espresso, abbiamo creato un set di codemods che ti aiuterà ad aggiornare automaticamente il tuo codice all'ultima versione di Express. + +Eseguire il seguente comando per eseguire tutte le codemods disponibili: + +```sh +npx codemod@latest @expressjs/v5-migration-ricetta +``` + +Se si desidera eseguire un codice specifico, è possibile eseguire il seguente comando: + +```sh +npx codemod@latest @expressjs/name-of-the-codemod +``` + +Puoi trovare la lista dei codici disponibili [here](https://codemod.link/express). + +## Modifiche in Express 5 + +**Metodi e proprietà rimosse** + + + +**Modificato** + + + +**Miglioramenti** + + + +## Metodi e proprietà rimossi + +Se si utilizza uno qualsiasi di questi metodi o proprietà nella tua app, si bloccherà. Quindi, avrai bisogno di cambiare la tua app dopo l'aggiornamento alla versione 5. + +### app.del() + +Express 5 non supporta più la funzione `app.del()`. Se si utilizza questa funzione, viene generato un errore. Per registrare i percorsi HTTP DELETE, utilizza invece la funzione `app.delete()`. + +Inizialmente, `del` è stato usato invece di `delete`, perché `delete` è una parola chiave riservata in JavaScript. Tuttavia, come ECMAScript 6, `delete` e altre parole chiave riservate possono essere legalmente utilizzati come nomi di proprietà. + + +È possibile sostituire le firme deprecate con il seguente comando: + +```plaintext +npx codemod@latest @expressjs/route-del-to-delete +``` + + + +```js +// v4 +app.del('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); + +// v5 +app. elete('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); +``` + +### app.param(fn) + +La firma `app.param(fn)` è stata usata per modificare il comportamento della funzione `app.param(name, fn)`. È stato deprecato dal v4.11.0, e Express 5 non lo supporta più. + +### Nomi dei metodi pluralizzati + +I seguenti nomi di metodo sono stati pluralizzati. In Express 4, utilizzando i vecchi metodi ha prodotto un avvertimento di deprecazione. Express 5 non li supporta più: + +`req.acceptsCharset()` è sostituito da `req.acceptsCharsets()`. + +`req.acceptsEncoding()` è sostituito da `req.acceptsEncodings()`. + +`req.acceptsLanguage()` è sostituito da `req.acceptsLanguages()`. + + +È possibile sostituire le firme deprecate con il seguente comando: + +```plaintext +npx codemod@latest @expressjs/pluralize-method-names +``` + + + +```js +// v4 +app.all('/', (req, res) => { + req.acceptsCharset('utf-8'); + req. cceptsEncoding('br'); + req.acceptsLanguage('en'); + + // ... +}); + +// v5 +app. ll('/', (req, res) => { + req.acceptsCharsets('utf-8'); + req.acceptsEncodings('br'); + req.acceptsLanguages('en'); + + // ... +}); +``` + +### Colon iniziale (:) nel nome di app.param(name, fn) + +Un carattere principale (:) nel nome della `app. aram(name, fn)` function is a remnant of Express 3, and for the sake of backwards compatity, Express 4 supported it with a deprecation notice. Express 5 lo ignorerà silenziosamente e userà il parametro del nome senza prefissarlo con un colon. + +Questo non dovrebbe influenzare il tuo codice se segui la documentazione Express 4 di [app.param](/en/4x/api#app.param), in quanto non fa alcuna menzione del colon principale. + +### req.param(nome) + +Questo metodo potenzialmente confuso e pericoloso di recupero dei dati del modulo è stato rimosso. Ora dovrai cercare in modo specifico il nome del parametro inviato nell'oggetto `req.params`, `req.body`, o `req.query`. + + +È possibile sostituire le firme deprecate con il seguente comando: + +```plaintext +npx codemod@latest @expressjs/explicit-request-params +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + const id = req.param('id'); + const body = req. aram('body'); + const query = req.param('query'); + + // ... +}); + +// v5 +app.post('/user', (req, res) => { + const id = req.params. d; + const body = req.body; + const query = req.query; + + // ... +}); +``` + +### res.json(obj, status) + +Express 5 non supporta più la firma `res.json(obj, status)`. Invece, impostare lo stato e poi catena il metodo `res.json()` così: `res.status(status).json(obj)`. + + +È possibile sostituire le firme deprecate con il seguente comando: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.json({ name: 'Ruben' }, 201); +}); + +// v5 +app. ost('/user', (req, res) => { + res.status(201).json({ name: 'Ruben' }); +}); +``` + +### res.jsonp(obj, status) + +Express 5 non supporta più la firma `res.jsonp(obj, status)`. Invece, impostare lo stato e poi catena il metodo `res.jsonp()` così: `res.status(status).jsonp(obj)`. + + +È possibile sostituire le firme deprecate con il seguente comando: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.jsonp({ name: 'Ruben' }, 201); +}); + +// v5 +app. ost('/user', (req, res) => { + res.status(201).jsonp({ name: 'Ruben' }); +}); +``` + +### res.redirect(url, status) + +Express 5 non supporta più la firma `res.redirect(url, status)`. Invece, utilizzare la seguente firma: `res.redirect(status, url)`. + + +È possibile sostituire le firme deprecate con il seguente comando: + +```plaintext +npx codemod@latest @expressjs/redirect-arg-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('/users', 301); +}); + +// v5 +app. et('/user', (req, res) => { + res.redirect(301, '/users'); +}); +``` + +### res.redirect('back') e res.location('back') + +Express 5 non supporta più la stringa magica `back` nei metodi `res.redirect()` e `res.location()`. Usa invece il valore `req.get('Referrer') '/'` per reindirizzare alla pagina precedente. In Express 4, i metodi `res.redirect('back')` e `res.location('back')` sono stati deprecati. + + +È possibile sostituire le firme deprecate con il seguente comando: + +```plaintext +npx codemod@latest @expressjs/back-redirect-deprecato +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('back'); +}); + +// v5 +app. et('/user', (req, res) => { + res.redirect(req.get('Referrer') '/'); +}); +``` + +### res.send(body, status) + +Express 5 non supporta più la firma `res.send(obj, status)`. Invece, imposta lo stato e poi la catena al metodo `res.send()` così: `res.status(status).send(obj)`. + + +È possibile sostituire le firme deprecate con il seguente comando: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send({ name: 'Ruben' }, 200); +}); + +// v5 +app. et('/user', (req, res) => { + res.status(200).send({ name: 'Ruben' }); +}); +``` + +### res.send(status) + +Express 5 non supporta più la firma `res.send(status)`, dove `status` è un numero. Invece, utilizzare `res. endStatus(statusCode)` funzione, che imposta il codice di stato dell'intestazione della risposta HTTP e invia la versione del testo del codice: "Not Found", "Errore interno del server", e così via. +Se è necessario inviare un numero utilizzando `res. la funzione end()`, cita il numero per convertirlo in una stringa, in modo che Express non lo interpreti come un tentativo di utilizzare la vecchia firma non supportata. + + +È possibile sostituire le firme deprecate con il seguente comando: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send(200); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendStatus(200); +}); +``` + +### res.sendfile() + +La funzione `res.sendfile()` è stata sostituita da una versione a cassa in camme `res.sendFile()` in Express 5. + +**Nota:** In Express 5, `res. endFile()` utilizza il pacchetto `mime-types` per il rilevamento del tipo MIME, che restituisce diversi valori di Content-Type rispetto a Express 4 per diversi tipi di file comuni: + +* File JavaScript (.js): ora "text/javascript" invece di "application/javascript" +* File JSON (.json): ora "application/json" invece di "text/json" +* File CSS (.css): ora "text/css" invece di "text/plain" +* File XML (.xml): ora "application/xml" invece di "text/xml" +* File dei caratteri (.woff): ora "font/woff" invece di "application/font-woff" +* File SVG (.svg): ora "image/svg+xml" invece di "application/svg+xml" + + +È possibile sostituire le firme deprecate con il seguente comando: + +```plaintext +npx codemod@latest @expressjs/camelcase sendfile +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.sendfile('/path/to/file'); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendFile('/path/to/file'); +}); +``` + +### router.param(fn) + +La firma `router.param(fn)` è stata utilizzata per modificare il comportamento della funzione `router.param(name, fn)`. È stato deprecato dal v4.11.0, e Express 5 non lo supporta più. + +### express.static.mime + +In Express 5, `mime` non è più una proprietà esportata del campo `static`. +Usa il pacchetto [`mime-types`](https://github.com/jshttp/mime-types) per lavorare con i valori del tipo MIME. + +**Importante:** Questa modifica influisce non solo sull'uso diretto di `express.static.mime` ma anche su altri metodi Express che si basano sul rilevamento del tipo MIME, come `res.sendFile()`. I seguenti tipi di MIME sono cambiati da Express 4: + +* File JavaScript (.js): ora servito come "text/javascript" invece di "application/javascript" +* File JSON (.json): ora servito come "application/json" invece di "text/json" +* File CSS (.css): ora servito come "text/css" invece di "text/plain" +* File HTML (): ora servito come "text/html; charset=utf-8" invece di "text/html" +* File XML (.xml): ora servito come "application/xml" invece di "text/xml" +* File di carattere (.woff): ora servito come "font/woff" invece di "application/font-woff" + +```js +// v4 +express.static.mime.lookup('json'); + +// v5 +const mime = require('mime-types'); +mime.lookup('json'); +``` + +### express:router debug log + +In Express 5, la logica di gestione del router viene eseguita da una dipendenza. Pertanto, i log di debug +per il router non sono più disponibili sotto lo spazio dei nomi `express:`. +In v4, i log erano disponibili sotto i namespace `express:router`, `express:router:layer`, +e `express:router:route`. Tutti questi sono stati inclusi nel namespace `express:*`. +In v5.1+, i log sono disponibili sotto i namespace `router`, `router:layer`, e `router:route`. +I log di `router:layer` e `router:route` sono inclusi nel namespace `router:*`. +Per ottenere lo stesso dettaglio di debug quando si utilizza `express:*` in v4, utilizzare una combinazione di +`express:*`, `router`, e `router:*`. + +```sh + +DEBUG=express:* node index.js + + +DEBUG=express:*,router,router:* node index.js +``` + +## Modificato + +### Sintassi percorso corrispondente + +Il percorso percorso corrispondente alla sintassi è quando una stringa viene fornita come primo parametro alle API `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, e `router.use()`. Sono state apportate le seguenti modifiche a come la stringa del percorso è abbinata a una richiesta in ingresso: + +* Il carattere jolly `*` deve avere un nome, corrispondente al comportamento dei parametri `:`, usa `/*splat` invece di `/*` + +```js +// v4 +app.get('/*', async (req, res) => { + res.send('ok'); +}); + +// v5 +app. et('/*splat', async (req, res) => { + res.send('ok'); +}); +``` + + +`*splat` corrisponde a qualsiasi percorso senza il percorso root. Se hai bisogno di abbinare anche il percorso radice `/`, puoi usare `/{*splat}`, avvolgendo il carattere jolly nelle graffe. + +```js +// v5 +app.get('/{*splat}', async (req, res) => { + res.send('ok'); +}); +``` + + + +* Il carattere opzionale `?` non è più supportato, utilizza invece le graffe. + +```js +// v4 +app.get('/:file.:ext?', async (req, res) => { + res.send('ok'); +}); + +// v5 +app. et('/:file{.:ext}', async (req, res) => { + res.send('ok'); +}); +``` + +* I caratteri Regexp non sono supportati. Per esempio: + +```js +app.get('/[discussion page]/:slug', async (req, res) => { + res.status(200).send('ok'); +}); +``` + +dovrebbe essere modificato in: + +```js +app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { + res.status(200).send('ok'); +}); +``` + +* Alcuni caratteri sono stati riservati per evitare confusione durante l'aggiornamento (`()[]?+!`), usa `\` per sfuggire a loro. +* I nomi dei parametri ora supportano identificativi JavaScript validi, o citati come `:"this"`. + +### Promesse respinte gestite da middleware e gestori + +Richiedi middleware e gestori che restituiscono le promesse rifiutate sono ora gestiti inoltrando il valore rifiutato come `Error` alla gestione degli errori middleware. Ciò significa che usare le funzioni `async` come middleware e manipolatori sono più facili che mai. Quando un errore viene lanciato in una funzione `async` o una promessa rifiutata è `await`ed all'interno di una funzione asincrona, questi errori verranno passati al gestore degli errori come se chiamasse `next(err)`. + +Dettagli su come Express gestisce gli errori sono coperti nella [documentazione relativa alla gestione degli errori](/en/guide/error-handling). + +### express.urlencoded + +Il metodo `express.urlencoded` rende l'opzione `extended` `false` per impostazione predefinita. + +### express.static dotfiles + +In Express 5, l'opzione `express.static` middleware `dotfiles` ora è predefinita per `"ignore"`. Questo è un cambiamento da Express 4, dove i dotfiles sono stati serviti per impostazione predefinita. Di conseguenza, i file all'interno di una directory che inizia con un punto (`.`), come `. ell-known`, non sarà più accessibile e restituirà un errore **404 non trovato**. Questo può rompere la funzionalità che dipende dal servizio di directory a punti, come Android App Links, e Apple Universal Links. + +Esempio di codice di rottura: + +```js +// v4 +app.use(express.static('public')); +``` + +Dopo la migrazione a Express 5, una richiesta a `/.well-known/assetlinks.json` comporterà un **404 Non Trovato**. + +Per risolvere questo problema, serve specifiche directory punti esplicitamente usando il file `dotes: "allow"` opzione: + +```js +// v5 +app.use('/.well-known', express.static('public/.well-known', { dotfiles: 'allow' })); +app.use(express.static('public')); +``` + +Questo approccio consente di servire in modo sicuro solo le directory punti desiderate mantenendo il comportamento sicuro predefinito per altri file dot, che rimangono inaccessibili. + +### app.listen + +In Express 5, il metodo `app.listen` richiamerà la funzione di callback fornita dall'utente (se fornita) quando il server riceve un evento di errore. In Express 4, tali errori verrebbero lanciati. Questa modifica sposta la responsabilità di gestione degli errori alla funzione di callback in Express 5. Se c'è un errore, verrà passato al callback come argomento. +Per esempio: + +```js +const server = app.listen(8080, '0.0.0.0', (error) => { + if (error) { + throw error; // e.g. EADDRINUSE + } + console.log(`Ascolto su ${JSON.stringify(server.address()}`); +}); +``` + +### app.router + +L'oggetto `app.router`, che è stato rimosso in Express 4, ha fatto una rimonta in Express 5. Nella nuova versione, questo oggetto è solo un riferimento al router base Express, a differenza di Express 3, dove un'app ha dovuto caricarla esplicitamente. + +### req.body + +La proprietà `req.body` restituisce `undefined` quando il corpo non è stato analizzato. In Express 4, restituisce `{}` per impostazione predefinita. + +### req.host + +In Express 4, la funzione `req.host` è stata eliminata in modo errato dal numero di porta se era presente. In Express 5, il numero di porta è mantenuto. + +### req.params + +L'oggetto `req.params` ora ha un **null prototipe** quando si usano i percorsi delle stringhe. Tuttavia, se il percorso è definito con un'espressione regolare, `req.params` rimane un oggetto standard con un prototipo normale. Inoltre, ci sono due importanti cambiamenti comportamentali: + +**I parametri Wildcard sono ora array:** + +I caratteri jolly (ad esempio, `/*splat`) catturano i segmenti di percorso come un array invece di una singola stringa. + +```js +app.get('/*splat', (req, res) => { + // GET /foo/bar + console.dir(req. arams); + // => [Object: null prototype] { splat: [ 'foo', 'bar' ] } +}); +``` + +**Parametri non corrispondenti sono omessi:** + +In Express 4, i caratteri jolly non corrispondenti erano stringhe vuote (`''`) e parametri opzionali `:` (usando `?`) avevano una chiave con valore `undefined`. In Express 5, i parametri non corrispondenti vengono completamente omessi da `req.params`. + +```js +// v4: wildcard unmatched is empty string +app.get('/*', (req, res) => { + // GET / + console.dir(req. aram); + // => { '0': '' } +}); + +// v4: il param opzionale non corrisponde è l'app +non definita. et('/:file.:ext?', (req, res) => { + // GET /image + console. ir(req.params); + // => { file: 'image', ext: undefined } +}); + +// v5: unmatched optional param is omitted +app.get('/:file{. ext}', (req, res) => { + // GET /image + console.dir(req. arams); + // => [Object: null prototype] { file: 'image' } +}); +``` + +### req.query + +La proprietà `req.query` non è più una proprietà scrivibile ed è invece un getter. Il parser di query predefinito è stato cambiato da "esteso" a "semplice". + +### res.clearCookie + +Il metodo `res.clearCookie` ignora le opzioni `maxAge` e `expires` fornite dall'utente. + +### res.status + +Il metodo `res.status` accetta solo interi nell'intervallo da `100` a `999`, seguendo il comportamento definito da Node. s, e restituisce un errore quando il codice di stato non è un numero intero. + +### res.vary + +Il file `res.vary` lancia un errore quando manca l'argomento `field`. In Express 4, se l'argomento è stato omesso, ha dato un avviso nella console + +## Miglioramenti + +### res.render() + +Questo metodo ora forza il comportamento asincrono per tutti i motori di visualizzazione, evitando bug causati da motori di visualizzazione che avevano un'implementazione sincrona e che violavano l'interfaccia raccomandata. + +### Supporto codifica Brotli + +Express 5 supporta la codifica Brotli per le richieste ricevute dai clienti che la supportano. diff --git a/src/content/pages/it/resources/glossary.mdx b/src/content/pages/it/resources/glossary.mdx new file mode 100644 index 0000000000..f28ec021a5 --- /dev/null +++ b/src/content/pages/it/resources/glossary.mdx @@ -0,0 +1,61 @@ +--- +title: Glossary +description: Un glossario completo di termini relativi a Express.js, Node.js, middleware, routing e altri concetti chiave per aiutarti a capire e utilizzare Express in modo efficace. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +### applicazione + +In generale, uno o più programmi che sono progettati per effettuare operazioni per uno scopo specifico. Nel contesto di Express, un programma che utilizza l'API Express in esecuzione sulla piattaforma Node.js. Potrebbe anche fare riferimento a un [app object](/en/api#express). + +### API + +Interfaccia di programmazione applicativa. Spiega l'abbreviazione quando viene usata per la prima volta. + +### Espresso + +Un framework web veloce, non opinabile, minimalista per applicazioni Node.js. In generale, "Express" è preferito a "Express.js", anche se quest'ultimo è accettabile. + +### libuv + +Una libreria di supporto multi-piattaforma che si concentra su I/O asincrono sviluppato principalmente per l'uso da Node.js. + +### middleware + +Una funzione che viene invocata dallo strato di routing Express prima del gestore finale della richiesta, e si siede così al centro tra una richiesta grezza e il percorso finale previsto. Alcuni punti di fine terminologia intorno al middleware: + +* `var foo = require('middleware')` si chiama *requiring* o *using* un modulo Node.js. Quindi la dichiarazione `var mw = foo()` restituisce tipicamente il middleware. +* `app.use(mw)` si chiama *aggiungendo il middleware allo stack globale di elaborazione*. +* `app.get('/foo', mw, function (req, res) { ... })` si chiama _aggiungendo il middleware allo stack di elaborazione "GET /foo" . + +### Node.js + +Una piattaforma software che viene utilizzata per costruire applicazioni di rete scalabili. Node.js utilizza JavaScript come linguaggio di scripting e raggiunge un elevato rendimento tramite I/O non bloccante e un ciclo di eventi a filettatura singola. Vedi [nodejs.org](https://nodejs.org/en/). **Nota di utilizzo**: Inizialmente, "Node.js," in seguito "Node". + +### open-source, open source + +Quando usato come aggettivo, ifenato; per esempio: "Questo è software open-source." Vedi [Software Open-source su Wikipedia](http://en.wikipedia.org/wiki/Open-source_software). + + + +Anche se è comune non trattenere questo termine, stiamo usando le regole standard inglesi per +che trattiene un aggettivo composto. + + + +### richiesta + +Una richiesta HTTP. Un client invia un messaggio di richiesta HTTP a un server, che restituisce una risposta. La richiesta deve utilizzare uno dei diversi [metodi di richiesta](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) come GET, POST, e così via. + +### risposta + +Una risposta HTTP. Un server restituisce un messaggio di risposta HTTP al client. La risposta contiene informazioni sullo stato di completamento della richiesta e potrebbe anche contenere contenuto richiesto nel suo corpo del messaggio. + +### percorso + +Parte di un URL che identifica una risorsa. Ad esempio, in `http://foo.com/products/id`, "/products/id" è il percorso. + +### router + +Vedi [router](/en/api#router) nel riferimento API. diff --git a/src/content/pages/it/resources/utils.md b/src/content/pages/it/resources/utils.md new file mode 100644 index 0000000000..4069421b0f --- /dev/null +++ b/src/content/pages/it/resources/utils.md @@ -0,0 +1,22 @@ +--- +title: Utilità Express +description: Scopri i moduli di utilità relativi a Express.js e Node.js, inclusi strumenti per cookie, protezione CSRF, analisi URL, routing e molto altro per migliorare le tue applicazioni. +--- + +## Funzioni di utilità Express + +L'organizzazione [pillarjs](https://github.com/pillarjs) GitHub contiene una serie di moduli +per funzioni di utilità che possono essere generalmente utili. + +| Moduli di utilità | Descrizione | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [cookies](https://www.npmjs.com/package/cookies) | Ottieni e imposta i cookie HTTP(S) che possono essere firmati per evitare manomissioni, utilizzando Keygrip. Può essere utilizzato con la libreria HTTP Node.js o come middleware Express. | +| [csrf](https://www.npmjs.com/package/csrf) | Contiene la logica dietro la creazione e la verifica del token CSRF. Usa questo modulo per creare middleware CSRF personalizzato. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Funzione di invocare come passo finale per rispondere alla richiesta HTTP. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Analizza un URL con la cache. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Trasforma una stringa di percorso in stile Express, come \`\`/user/:name\` in un'espressione regolare. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Risolve un percorso relativo contro un percorso radice con convalida. | +| [router](https://www.npmjs.com/package/router) | Semplice router in stile middleware. | +| [send](https://www.npmjs.com/package/send) | Libreria per lo streaming di file come risposta HTTP, con supporto per risposte parziali (intervalli), negoziazione condizionale-GET ed eventi granulari. | + +Per ulteriori moduli correlati all'HTTP di basso livello, vedere [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/it/support.md b/src/content/pages/it/support.md new file mode 100644 index 0000000000..caec4f1d23 --- /dev/null +++ b/src/content/pages/it/support.md @@ -0,0 +1,23 @@ +--- +title: Supporto Versione +description: Trova informazioni sul programma di supporto per le diverse versioni di Express.js, comprese le versioni attualmente mantenute e le politiche di fine vita. +--- + +È supportata solo l'ultima versione di una data linea di rilascio principale. + +Versioni che sono EOL (end-of-life) _may_ ricevere aggiornamenti per le vulnerabilità di sicurezza critiche, ma il team Express non offre alcuna garanzia e non prevede di affrontare o risolvere i problemi riscontrati. + +| Versione Maggiore | Versione Minima Node.js | Data Inizio Supporto | Data Di Fine Supporto | +| ------------------------------------------- | --------------------------------------- | -------------------- | --------------------- | +| [**v5.x**](/en/5x/api) | 18 | Settembre 2024 | **in corso** | +| [**v4.x**](/en/4x/api) | 0.10.0 | Aprile 2014 | **in corso** | +| [**v3.x**](/en/3x/api) | 0.8.0 | Ottobre 2012 | Luglio 2015 | +| [**v2.x**](/2x/) | 0.4.1 | Marzo 2011 | Luglio 2012 | +| **v1.x** | 0.2.0 | Dicembre 2010 | Marzo 2011 | +| **v0.14.x** | 0.1.98 | Dicembre 2010 | Dicembre 2010 | + +## Opzioni Di Supporto Commerciale + +Se non riesci ad aggiornare ad una versione supportata di Express, contatta uno dei nostri partner per ricevere aggiornamenti di sicurezza: + +- [HeroDevs Never-Ending Support](http://www.herodevs.com/support/express-nes?utm_source=expressjs&utm_medium=link&utm_campaign=express_eol_page) diff --git a/src/content/pages/ja/advanced/best-practice-performance.md b/src/content/pages/ja/advanced/best-practice-performance.md new file mode 100644 index 0000000000..8ec6ee7e87 --- /dev/null +++ b/src/content/pages/ja/advanced/best-practice-performance.md @@ -0,0 +1,305 @@ +--- +title: '生産のベストプラクティス：性能と信頼性' +description: 実稼働中の Express アプリケーションのパフォーマンスと信頼性のベストプラクティスをご覧ください。最適なパフォーマンスを得るためのコードの最適化と環境設定を網羅しています。 +--- + +この記事では、本番環境にデプロイされた Express アプリケーションのパフォーマンスと信頼性のベストプラクティスについて説明します。 + +このトピックは、伝統的な開発と運営の両方にまたがる"devops"の世界にはっきりと当てはまります。 したがって、情報は以下の2つに分かれています。 + +- コード内で行うべきこと（開発部分）： + - [Use gzip compression](#use-gzip-compression) + - [Don't use synchronous functions](#dont-use-synchronous-functions) + - [Do logging correctly](#do-logging-correctly) + - [Handle exceptions properly](#handle-exceptions-properly) +- あなたの環境/セットアップで行うべきこと（オプスパート）： + - [NODE_ENV を "production"に設定] (#set-node_env-to-production) + - [Ensure your app automatically restarts](#ensure-your-app-automatically-restarts) + - [Run your app in a cluster](#run-your-app-in-a-cluster) + - [Cache request results](#cache-request-results) + - [Use a load balancer](#use-a-load-balancer) + - [Use a reverse proxy](#use-a-reverse-proxy) + +## コード内でやるべきこと + +コードでアプリケーションのパフォーマンスを向上させるためにできることをいくつか紹介します。 + +- [Use gzip compression](#use-gzip-compression) +- [Don't use synchronous functions](#dont-use-synchronous-functions) +- [Do logging correctly](#do-logging-correctly) +- [Handle exceptions properly](#handle-exceptions-properly) + +### gzip 圧縮を使用する + +Gzip 圧縮は応答本体のサイズを大幅に減らすことができるので、ウェブアプリの速度を向上させます。 エクスプレスアプリでgzip圧縮用の [compression](https://www.npmjs.com/package/compression) ミドルウェアを使用してください。 例: + +```js +const compression = require('compression'); +const express = require('express'); +const app = express(); + +app.use(compression()); +``` + +For a high-traffic website in production, the best way to put compression in place is to implement it at a reverse proxy level (see [Use a reverse proxy](#use-a-reverse-proxy)). その場合、圧縮ミドルウェアを使用する必要はありません。 Nginx で gzip 圧縮を有効にする方法については、Nginx ドキュメントの [Module ngx_http_gzip_module](http://nginx.org/en/docs/http/ngx_http_gzip_module) を参照してください。 + +### 同期関数を使用しない + +同期関数とメソッドは、実行中のプロセスを返すまで結びつけます。 同期関数への単一の呼び出しは、数マイクロ秒またはミリ秒で戻る可能性があります。 しかし、交通量の多いウェブサイトでは、これらの呼び出しはアプリのパフォーマンスを向上させ、削減します。 生産での使用を避けます。 + +Node と多くのモジュールは同期バージョンと非同期バージョンの関数を提供しますが、本番環境では常に非同期バージョンを使用します。 同期関数を正当化できる唯一の時間は、最初の起動時です。 + +`--trace-sync-io` コマンドラインフラグを使用すると、アプリケーションが同期 API を使用するたびに警告とスタックトレースを表示できます。 もちろん、本番環境では使用したくないのではなく、コードが本番環境で使用できるようにしてください。 詳細は [node command-line options documentation](https://nodejs.org/api/cli#cli_trace_sync_io) を参照してください。 + +### 正しくログを行う + +一般的に、アプリからログを記録するには、次の2つの理由があります。デバッグとアプリアクティビティのロギング(基本的には他のすべて)です。 `console.log()` または `console.error()` を使って、ターミナルにログメッセージを出力するのが一般的です。 デスティネーションが端末やファイルの場合、[これらの関数は同期されます](https://nodejs.org/api/console#console) 別のプログラムに出力を送らない限り生産には向いていません + +#### デバッグ用 + +デバッグの目的でログを記録する場合は、 `console.log()` の代わりに、 [debug](https://www.npmjs.com/package/debug) のような特別なデバッグモジュールを使用してください。 このモジュールにより、DEBUG 環境変数を使用して `console.error()` に送信されるデバッグメッセージを制御することができます。 アプリケーションを純粋に非同期に保つために、`console.error()`を別のプログラムにパイプします。 しかし、実際に本番環境でデバッグするつもりはありませんね。 + +#### アプリのアクティビティ用 + +アプリのアクティビティを記録している場合 (トラフィックや API コールのトラッキングなど)、コンソールを使用する代わりに。 og()\`は、 [Pino](https://www.npmjs.com/package/pino)のようなロギングライブラリを使用します。これは利用可能な最速かつ最も効率的なオプションです。 + +### 例外を適切に処理する + +ノードアプリは、キャッチされていない例外に遭遇するとクラッシュします。 例外を処理せず、適切なアクションを実行すると、Express アプリがクラッシュしてオフラインになります。 If you follow the advice in [Ensure your app automatically restarts](#ensure-your-app-automatically-restarts) below, then your app will recover from a crash. 幸いなことに、Expressアプリは通常、短い起動時間を持っています。 それにもかかわらず、あなたは最初の場所でクラッシュを避けたいし、それを行うには、適切な例外を処理する必要があります。 + +すべての例外を確実に処理するには、以下の手法を使用します。 + +- [Use try-catch](#use-try-catch) +- [Use promises](#use-promises) + +これらのトピックに取り組む前に、Node/Express エラー処理の基本的な理解を持っている必要があります。すなわち、error-first コールバックの使用、およびミドルウェアのエラーの伝播です。 ノードは、非同期関数からエラーを返すために "error-first callback" 規則を使用します。 コールバック関数の最初のパラメータがエラーオブジェクトであり、続くパラメータの結果データが続きます。 エラーがないことを示すには、最初のパラメータとして null を指定します。 コールバック関数は、エラーを有意義に処理するために、error-first コールバック規約に従わなければなりません。 Express では、next() 関数を使用してミドルウェアチェーンを通じてエラーを伝播させるのがベストプラクティスです。 + +エラー処理の基礎については、以下を参照してください。 + +- [Error Handling in Node.js](https://www.tritondatacenter.com/node-js/production/design/errors) + +#### Try-catchを使用 + +Try-catch は同期コードで例外をキャッチするために使用できる JavaScript 言語構造です。 例えば、以下のように JSON 解析エラーを処理するには、try-catch を使用します。 + +ここでは、プロセスクラッシュの可能性がある例外を処理するために try-catch を使用した例を示します。 +このミドルウェア関数は、JSONオブジェクトである"params"という名前のクエリフィールドパラメータを受け取ります。 + +```js +app.get('/search', (req, res) => { + // Simulating async operation + setImmediate(() => { + const jsonStr = req.query.params; + try { + const jsonObj = JSON.parse(jsonStr); + res.send('Success'); + } catch (e) { + res.status(400).send('Invalid JSON string'); + } + }); +}); +``` + +しかし、try-catch は同期コードでのみ動作します。 Node プラットフォームは主に (特に本番環境では) 非同期であるため、try-catch は多くの例外をキャッチしません。 + +#### Promiseの使用 + +`async` 関数内でエラーがスローされた場合、または `async` 関数内で rejected Promise が待機されます。 これらのエラーは、`next(err)`を呼び出すかのようにエラーハンドラに渡されます。 + +```js +app.get('/', async (req, res, next) => { + const data = await userData(); // If this promise fails, it will automatically call `next(err)` to handle the error. + + res.send(data); +}); + +app.use((err, req, res, next) => { + res.status(err.status ?? 500).send({ error: err.message }); +}); +``` + +また、ミドルウェアに非同期関数を使用することもできますし、promiseが失敗した場合にルーターがエラーを処理します。例えば: + +```js +app.use(async (req, res, next) => { + req.locals.user = await getUser(req); + + next(); // This will be called if the promise does not throw an error. +}); +``` + +ベストプラクティスは、できるだけサイトに近いエラーを処理することです。 これはルータで処理されていますが ミドルウェアでエラーをキャッチし、別々のエラー処理ミドルウェアに頼らずに処理するのが最善です。 + +#### 何をしないか + +`unchaughtException`をリッスンするのは_しないでください。 イベントループに戻るまで例外が発生した場合に発生します。 `uncaughtException` に対してイベントリスナーを追加すると、例外に遭遇するプロセスのデフォルトの動作が変更されます。 例外にもかかわらずこのプロセスは続けられます これはアプリがクラッシュするのを防ぐ良い方法に思えるかもしれません。 しかし、未取得の例外が危険な方法であり、推奨されていない場合、アプリを実行し続けます。 プロセスの状態は信頼できず予測不能になるからです + +さらに、 `uncaughtException` を使用すると、公式に [crude](https://nodejs.org/api/process#process_event_uncaughtexception) として認識されます。 ですから、 `unchaughtException` を聴くのは悪い考えです。 このため、複数のプロセスやスーパーバイザのようなものをお勧めします。クラッシュと再起動は、多くの場合、エラーから回復する最も信頼性の高い方法です。 + +また、 [domains](https://nodejs.org/api/domain) の使用はお勧めしません。 これは一般的に問題を解決せず、非推奨のモジュールです。 + +## 環境/設定 + +以下は、アプリのパフォーマンスを向上させるためにシステム環境でできるいくつかのことです。 + +- [NODE_ENV を "production"に設定] (#set-node_env-to-production) +- [Ensure your app automatically restarts](#ensure-your-app-automatically-restarts) +- [Run your app in a cluster](#run-your-app-in-a-cluster) +- [Cache request results](#cache-request-results) +- [Use a load balancer](#use-a-load-balancer) +- [Use a reverse proxy](#use-a-reverse-proxy) + +### NODE_ENV を "production" に設定 + +NODE_ENV 環境変数は、アプリケーションが実行されている環境 (通常は開発または実装) を指定します。 パフォーマンスを向上させるためにできる最も簡単なことの一つは、NODE_ENV を `production` に設定することです。 + +NODE_ENV を "production" に設定すると Express: + +- ビューテンプレートのキャッシュ。 +- CSS 拡張機能から生成された CSS ファイルをキャッシュします。 +- あまり冗長なエラーメッセージを生成します。 + +[Tests indicate](https://www.dynatrace.com/news/blog/the-drastic-effects-of-omitting-node-env-in-your-express-js-applications/) これを行うだけでアプリのパフォーマンスが3倍向上することができます! + +環境固有のコードを書く必要がある場合は、 `process.env.NODE_ENV` でNODE_ENVの値を確認できます。 環境変数の値をチェックするとパフォーマンスペナルティが発生するため、慎重に行う必要があります。 + +開発では、通常、 `export` または `.bash_profile` ファイルを使用して、対話型シェルで環境変数を設定します。 しかし、一般的には、本番サーバーでそれを行うべきではありません。代わりに、OS の init システム (systemd) を使用します。 次のセクションでは、init システム一般の使用法についての詳細を説明します。 しかし、`NODE_ENV`を設定することはパフォーマンスにとってとても重要です(そして実行しやすいので、ここでハイライトされています)。 + +systemdでは、ユニットファイルの中で`Environment`ディレクティブを使用します。 例: + +```sh + +Environment=NODE_ENV=production +``` + +詳細については、[systemd 単位で環境変数を使用する](https://www.flatcar.org/docs/latest/setup/systemd/environment-variables/)を参照してください。 + +### アプリが自動的に再起動することを確認します + +本番環境では、アプリケーションをオフラインにしたくありません。 つまり、アプリがクラッシュした場合とサーバー自体がクラッシュした場合の両方が再起動することを確認する必要があります。 これらのイベントのどちらも発生しないことを願っていますが、現実的には両方のイベントを次のように説明する必要があります。 + +- プロセス・マネージャーを使用して、クラッシュしたときにアプリ(およびノード)を再起動します。 +- OS がクラッシュしたときに、OS が提供する init システムを使用して、プロセス マネージャを再起動します。 プロセス管理者なしで init システムを使用することもできます。 + +ノードアプリケーションは、キャッチされていない例外が発生した場合にクラッシュします。 The foremost thing you need to do is to ensure your app is well-tested and handles all exceptions (see [handle exceptions properly](#handle-exceptions-properly) for details). しかし、フェイルセーフとして、アプリがクラッシュしたときに自動的に再起動するようにメカニズムを導入します。 + +#### プロセス管理者を使用する + +開発では、コマンドラインから `node server.js` などでアプリを起動しました。 しかし、生産でこれを行うことは災害のレシピです。 アプリがクラッシュすると、再起動するまでオフラインになります。 クラッシュした場合にアプリを再起動させるには、プロセスマネージャーを使用します。 プロセス マネージャは、デプロイを容易にし、高可用性を提供し、実行時にアプリケーションを管理することができるアプリケーションの「コンテナ」です。 + +クラッシュ時にアプリを再起動することに加え、プロセスマネージャーは以下を可能にします: + +- ランタイムのパフォーマンスとリソース消費に関する洞察を得ます。 +- パフォーマンスを向上させるために動的に設定を変更します。 +- 制御クラスタリング (pm2) + +歴史的には、 [PM2](https://github.com/Unitech/pm2) のような Node.js プロセス管理者を使用することが一般的でした。 これを行いたい場合は、ドキュメントを参照してください。 ただし、プロセス管理に init システムを使用することをお勧めします。 + +#### init システムを使用します + +信頼性の次の層は、サーバーの再起動時にアプリが再起動することを確認することです。 システムはまださまざまな理由でダウンすることができます。 サーバーがクラッシュした場合にアプリが再起動するようにするには、OS に組み込まれた init システムを使用します。 今日使用されている主な init システムは [systemd](https://wiki.debian.org/systemd) です。 + +Express アプリで init システムを使用するには、次の 2 つの方法があります。 + +- プロセス・マネージャーでアプリを実行し、init システムを使用したサービスとしてプロセス・マネージャをインストールします。 アプリがクラッシュしたときにプロセスマネージャーがアプリを再起動し、OS の再起動時に init システムがプロセスマネージャーを再起動します。 これは推奨されるアプローチです。 +- init システムを使用して、アプリケーションを直接実行します。 これはいくらか簡単ですが、プロセスマネージャーを使用することの追加の利点を得ることはありません。 + +##### Systemd + +SystemdはLinuxシステムとサービスマネージャーです。 ほとんどの主要な Linux ディストリビューションでは、systemd をデフォルトの init システムとして採用しています。 + +systemd サービスの設定ファイルは _unit file_と呼ばれ、ファイル名は `.service` で終わります。 Nodeアプリケーションを直接管理するためのユニットファイルの例を示します。 ``で囲まれたシステムとアプリの値を置き換えます。 + +```sh +[Unit] +Description= + +[Service] +Type=simple +ExecStart=/usr/local/bin/node +WorkingDirectory= + +User=nobody +Group=nogroup + + +Environment=NODE_ENV=production + + +LimitNOFILE=infinity + + +LimitCORE=infinity + +StandardInput=null +StandardOutput=syslog +StandardError=syslog +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +systemd の詳細については、[systemd reference (man page)](http://www.freedesktop.org/software/systemd/man/systemd.unit)を参照してください。 + +### クラスターでアプリを実行 + +マルチコアシステムでは、プロセスのクラスタを起動することで、Node アプリケーションのパフォーマンスを何度も向上させることができます。 クラスタはアプリケーションの複数のインスタンスを実行し、理想的には各 CPU コアで 1 つのインスタンスを実行し、負荷とタスクをインスタンス間で分配します。 + +![Balancing between application instances using the cluster API](/images/clustering.png) + +重要: アプリケーション・インスタンスは別々のプロセスとして実行されるため、同じメモリ・スペースは共有されません。 つまり、オブジェクトはアプリの各インスタンスに対してローカルです。 したがって、アプリケーションコードで状態を維持することはできません。 ただし、 [Redis](http://redis.io/) のようなインメモリデータストアを使用してセッション関連のデータや状態を保存することができます。 この注意は、基本的には全ての形態の水平スケーリングに適用され、複数のプロセスまたは複数の物理サーバーでのクラスタリングに適用されます。 + +クラスター化されたアプリケーションでは、ワーカープロセスは他のプロセスに影響を与えることなく個別にクラッシュする可能性があります。 パフォーマンス上の利点とは別に、アプリケーションプロセスのクラスタを実行するもう一つの理由は、障害の分離です。 ワーカープロセスがクラッシュするたびに、常にイベントをログに記録し、cluster.fork() を使用して新しいプロセスを生成するようにしてください。 + +#### ノードのクラスタモジュールの使用 + +ノードの [cluster module](https://nodejs.org/api/cluster) でクラスタリングが可能になりました。 これにより、マスタープロセスはワーカープロセスを生成し、ワーカー間の受信接続を分配することができます。 + +#### PM2の使用 + +PM2を使用してアプリケーションをデプロイする場合は、_without_アプリケーションコードを変更するクラスタリングを利用できます。 [application is stateless](https://pm2.keymetrics.io/docs/usage/specifics/#stateless-apps) を最初に確認してください。 つまり、プロセスにローカルデータは保存されません(セッション、WebSocket接続など)。 + +PM2を使用してアプリケーションを実行する場合、**クラスタモード**を有効にして、選択した複数のインスタンスを使用してクラスタで実行できます。 例えば、マシン上の利用可能なCPU数と一致するなど。 `pm2`コマンドラインツールを使って、クラスタ内のプロセス数を手動で変更できます。 + +クラスタモードを有効にするには、以下のようにアプリケーションを起動します。 + +```bash + +$ pm2 start npm --name my-app -i 4 -- start + +$ pm2 start npm --name my-app -i max -- start +``` + +これは PM2 プロセス ファイル (`ecosystem.config ) 内で設定することもできます。 `exec_mode`を`cluster`に、`instances\`を開始するワーカーの数に設定します。 + +一度実行すると、アプリケーションは次のようにスケーリングできます。 + +```bash + +$ pm2 scale my-app +3 + +$ pm2 scale my-app 2 +``` + +For more information on clustering with PM2, see [Cluster Mode](https://pm2.keymetrics.io/docs/usage/cluster-mode/) in the PM2 documentation. + +### キャッシュリクエストの結果 + +本番環境のパフォーマンスを向上させるもう一つの戦略は、リクエストの結果をキャッシュすることです。 アプリが同じリクエストを繰り返し処理しないようにします。 + +[Varnish](https://www.varnish-cache.org/) や [Nginx](https://blog.nginx.org/blog/nginx-caching-guide) のようなキャッシュサーバーを使用して、アプリの速度とパフォーマンスを大幅に向上させます。([Nginx Caching](https://serversforhackers.com/nginx-caching/)) を参照してください。 + +### ロードバランサーを使用 + +どんなに最適化されたアプリであっても、1つのインスタンスは限られた負荷とトラフィックしか処理できません。 アプリを拡張する方法の1つは、アプリの複数のインスタンスを実行し、ロードバランサを介してトラフィックを分散することです。 ロードバランサを設定すると、アプリのパフォーマンスと速度が向上し、1つのインスタンスでより多くのスケールが可能になります。 + +ロードバランサは通常、複数のアプリケーションインスタンスとサーバーとの間でトラフィックをオーケストレーションするリバースプロキシです。 アプリのロードバランサーは、 [Nginx](https://nginx.org/en/docs/http/load_balancing) または [HAProxy](https://www.digitalocean.com/community/tutorials/an-introduction-to-haproxy-and-load-balancing-concepts) を使用して簡単に設定できます。 + +ロードバランシングでは、特定のセッション ID に関連付けられているリクエストがそれらを起動したプロセスに接続されていることを確認する必要があります。 これは_session affinity_または_sticky sessions_として知られています。 そして、セッションデータにRedisなどのデータストアを使用するために上記の提案によって対処される場合があります(アプリケーションによって異なります)。 For a discussion, see [Using multiple nodes](https://socket.io/docs/v4/using-multiple-nodes/). + +### リバースプロキシを使用 + +リバースプロキシは Web アプリの前にあり、リクエストをアプリに指示するのとは別に、リクエストに対するサポート操作を行います。 これは、エラーページ、圧縮、キャッシュ、ファイルの提供、および他の間の負荷分散を処理することができます。 + +アプリケーション状態の知識を必要としないタスクをリバースプロキシに引き渡すと、Express を解放して専用のアプリケーションタスクを実行できます。 このため、Express はプロダクション環境で [Nginx](https://www.nginx.org/) や [HAProxy](https://www.haproxy.org/) のようなリバースプロキシの後ろで Express を実行することをお勧めします。 diff --git a/src/content/pages/ja/advanced/best-practice-security.mdx b/src/content/pages/ja/advanced/best-practice-security.mdx new file mode 100644 index 0000000000..593c000bf5 --- /dev/null +++ b/src/content/pages/ja/advanced/best-practice-security.mdx @@ -0,0 +1,276 @@ +--- +title: プロダクションのベストプラクティス：セキュリティ +description: 運用中のExpressアプリのセキュリティベストプラクティス(TLSの使用、入力検証、セキュリティ保護されたCookieの使用、脆弱性の防止など)をご覧ください。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +*"production"* という用語は、アプリケーションや API がエンドユーザーや消費者に一般的に提供されるソフトウェアのライフサイクルにおける段階を指します。 対照的に、_"development"_段階では、コードを積極的に書いたりテストしたりしており、アプリケーションは外部からのアクセスに開かれていません。 対応するシステム環境はそれぞれ *production* と *development* と呼ばれています。 + +開発環境と生産環境は通常、異なる設定であり、非常に異なる要件を持っています。 開発で問題のあるものは、生産では受け入れられないかもしれません。 たとえば、開発環境では、デバッグ用のエラーの詳細なロギングを行うことができます。 同じ行動が本番環境ではセキュリティ上の懸念になることがあります 開発では拡張性、信頼性、パフォーマンスを心配する必要はありませんが、それらの懸念は生産において重要になります。 + + + +Express でセキュリティ上の脆弱性を発見したと思われる場合は、Security +ポリシーと手順をご覧ください。 + + + +実稼働中の Express アプリケーションのセキュリティのベスト プラクティスは以下のとおりです。 + +* [プロダクションのベストプラクティス: セキュリティ] (#production-best-practices-security) + * [Overview](#overview) + * [Expressの非推奨バージョンや脆弱バージョンを使用しないでください](#dont-use-deprecated-or-vulnerable-versions-of-express) + * [Use TLS](#use-tls) + * [Do not trust user input](#do-not-trust-user-input) + * [Prevent open redirects](#prevent-open-redirects) + * [Use Helmet](#use-helmet) + * [Reduce fingerprinting](#reduce-fingerprinting) + * [Use cookies securely](#use-cookies-securely) + * [Don't use the default session cookie name](#dont-use-the-default-session-cookie-name) + * [Set cookie security options](#set-cookie-security-options) + * [Prevent brute-force attacks against authorization](#prevent-brute-force-attacks-against-authorization) + * [Ensure your dependencies are secure](#ensure-your-dependencies-are-secure) + * [Avoid other known vulnerabilities](#avoid-other-known-vulnerabilities) + * [Additional considerations](#additional-considerations) + +## 非推奨または脆弱なバージョンの Express を使用しない + +Express 2.x と 3.x はメンテナンスされなくなりました。 これらのバージョンのセキュリティとパフォーマンスの問題は修正されません。 それらを使用しないでください! If you haven't moved to version 4, follow the [migration guide](/en/guide/migrating-4) or consider [Commercial Support Options](/en/support#commercial-support-options). + +Also ensure you are not using any of the vulnerable Express versions listed on the [Security updates page](/en/advanced/security-updates). もしそうであれば、安定版リリースのいずれかにアップデートしてください。 + +## TLS を使用 + +機密データを扱ったり転送したりする場合は、[Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) を使用して接続とデータを保護します。 この技術は、クライアントからサーバーに送信される前にデータを暗号化し、一般的な(そして簡単な)ハッキングを防ぎます。 Ajax と POST リクエストは目に見えて明らかではなく、ブラウザーでは「非表示」に見えるかもしれません。 彼らのネットワークトラフィックは、[パケットスニッフィング](https://en.wikipedia.org/wiki/Packet_analyzer)と[man-in-the-middle攻撃](https://en.wikipedia.org/wiki/Man-in-the-middle_attack)に対して脆弱です。 + +You may be familiar with Secure Socket Layer (SSL) encryption. [TLS は、単に SSLの次の進行である](\)。 言い換えれば、以前SSLを使用していた場合は、TLSへのアップグレードを検討してください。 一般的に、Nginx は TLS を扱うことをお勧めします。 Nginx (および他のサーバ) で TLS を設定するための参考情報については、[推奨サーバー構成 (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations)を参照してください。 + +Also, a handy tool to get a free TLS certificate is [Let's Encrypt](https://letsencrypt.org/about/), a free, automated, and open certificate authority (CA) provided by the [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). + +## ユーザー入力を信頼しない + +Webアプリケーションの場合、最も重要なセキュリティ要件の1つは、適切なユーザー入力検証と処理です。 これは多くの形態で来て、我々はここでそれらのすべてをカバーしません。 +最終的に、アプリケーションが受け入れるユーザー入力の種類を検証し、正しく処理する責任はあなたのものです。 + +### 開いているリダイレクトを防止 + +潜在的に危険なユーザー入力の例は *open redirect* です。 ここで、アプリケーションはユーザー入力としてURLを受け入れます (多くの場合、URLクエリでは、例えば`? rl=https://example. om`) `res.redirect` を使用して、 `location` ヘッダーを設定し、 +は 3xx ステータスを返します。 + +アプリケーションは、フィッシングサイトなどの悪意のあるリンクにユーザーを送信しないように、着信URLへのリダイレクトをサポートしていることを検証する必要があります。 他のリスクの中でもね + +`res.redirect`または`res.location`を使用する前にURLをチェックする例を示します。 + +```js +app.use((req, res) => { + try { + if (new Url(req.query.url).host !== 'example.com') { + return res.status(400).end(`Unsupported redirect to host: ${req.query.url}`); + } + } catch (e) { + return res.status(400).end(`Invalid url: ${req.query.url}`); + } + res.redirect(req.query.url); +}); +``` + +## ヘルメットを使用 + +[Helmet][helmet] は、HTTPヘッダーを適切に設定することで、よく知られているWeb脆弱性からアプリを保護するのに役立ちます。 + +Helmet は、セキュリティ関連の HTTP レスポンスヘッダーを設定するミドルウェア機能です。 ヘルメットは、デフォルトで次のヘッダーを設定します。 + +* `Content-Security-Policy`: 多くの攻撃を軽減するためにあなたのページで何が起こるかを許可する強力なリスト +* `Cross-Origin-Opener-Policy`: あなたのページを分離するのに役立ちます +* `Cross-Origin-Resource-Policy`: クロスオリジンからリソースを読み込むことをブロックします +* `Origin-Agent-Cluster`: プロセスの分離を元ベースに変更します +* `Referrer-Policy`: [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) ヘッダーを制御します +* `Strict-Transport-Security`: HTTPSを好むようブラウザーに教える +* `X-Content-Type-Options`: 回避 [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +* `X-DNS-Prefetch-Control`: DNS プリフェッチを制御します +* `X-Download-Options`: 強制的にダウンロードを保存します (Internet Explorerのみ) +* `X-Frame-Options`: [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) 攻撃を軽減する従来のヘッダー +* `X-Permitted-Cross-Domain-Policies`: Acrobat など、Adobe 製品のクロスドメイン動作を制御します +* `X-Powered-By`: Webサーバーに関する情報。 簡単な攻撃で使用できるため削除されました +* `X-XSS-Protection`: [XSS アタック]（https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting）を軽減しようとするレガシーヘッダーが悪化するため、ヘルメットは無効にします + +各ヘッダーは、設定または無効にできます。 詳細については、[its documentation website][helmet] をご覧ください。 + +他のモジュールと同様にヘルメットをインストール： + +```bash +$ npm install helmet +``` + +次に、コードでそれを使用します: + +```js +// ... + +const helt = require('helmet'); +app.use(helmet()); + +// ... +``` + +## フィンガープリントを減らす + +サーバーが使用する +ソフトウェアを判断する攻撃者の能力を低下させるために、セキュリティの追加層を提供するのに役立ちます。 「指紋」として知られています セキュリティ問題自体ではありませんが、 +アプリケーションの指紋化能力を低下させることで、セキュリティ全体の姿勢が改善されます。 +サーバーソフトウェアは、例えば、 +HTTPレスポンスヘッダのように、特定のリクエストにどのように応答するかの癖でフィンガープリントすることができます。 + +By default, Express sends the `X-Powered-By` response header that you can +disable using the `app.disable()` method: + +```js +app.disable('x-powered-by'); +``` + + + +`X-Powered-By header` を無効にすると、洗練された攻撃者が Express を実行していることを +判断できません。 カジュアルなエクスプロイトを妨げるかもしれませんが、アプリがExpressを実行していることを +判断する他の方法があります。 + + + +Expressはまた、独自のフォーマットされた「404 Not Found」メッセージとフォーマッタエラー +応答メッセージを送信します。 これらは、 +[自分の見つからないハンドラを追加する](/en/starter/faq#how-do-i-handle-404-responses) +と +[自分のエラーハンドラを書く](/en/guide/error-handling#writing-error-handlers): によって変更できます。 + +```js +// last app.use calls right before app.listen(): + +// custom 404 +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); + +// custom error handler +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +## Cookieを安全に使用 + +クッキーが悪用されるようにアプリを開かないようにするため、デフォルトのセッションクッキー名を使用しないでください。また、クッキーのセキュリティオプションを適切に設定してください。 + +2つの主なミドルウェアのセッションモジュールがあります。 + +* `express.session`ミドルウェアをExpress 3.xに置き換える[express-session](https://www.npmjs.com/package/express-session) +* `express.cookieSession` ミドルウェアをExpress 3.xに置き換える[cookie-session](https://www.npmjs.com/package/cookie-session) + +これらの2つのモジュールの主な違いは、クッキーセッションデータの保存方法です。 [express-session](https://www.npmjs.com/package/express-session) ミドルウェアは、セッションデータをサーバー上に保存します。セッションIDは、セッションデータではなく、クッキー自体にのみ保存します。 デフォルトでは、インメモリストレージを使用し、本番環境用に設計されていません。 本番環境では、スケーラブルな session-store を設定する必要があります。[compatible session store](https://github.com/expressjs/session#compatible-session-stores) のリストを参照してください。 + +対照的に、 [cookie-session](https://www.npmjs.com/package/cookie-session) middleware は、セッションキーだけではなく、セッション全体を Cookie にシリアライズします。 セッションデータが比較的小さく、(オブジェクトではなく)プリミティブ値としてエンコードしやすい場合にのみ使用してください。 ブラウザはクッキーごとに少なくとも4096バイトをサポートすることになっていますが。 制限を超えないようにするには、ドメインあたり4093バイトのサイズを超えないようにします。 また、クッキーデータがクライアントに表示されることに注意してください ですから、もしそれを安全または不明瞭に保つ理由がある場合は、 `express-session` はより良い選択かもしれません。 + +### デフォルトのセッションクッキー名を使用しない + +デフォルトのセッションクッキー名を使用すると、あなたのアプリを攻撃することができます。 提起されたセキュリティ上の問題は `X-Powered-By` と似ています。潜在的な攻撃者がそれを使用してサーバーにフィンガープリントを行い、それに応じて攻撃を標的にすることができます。 + +この問題を回避するには、ジェネリックな Cookie 名を使用してください。例えば、 [express-session](https://www.npmjs.com/package/express-session) ミドルウェアを使用してください。 + +```js +const session = require('express-session'); +app.set('trust proxy', 1); // trust first proxy +app.use( + session({ + secret: 's3Cur3', + name: 'sessionId', + }) +); +``` + +### Cookie のセキュリティオプションを設定 + +セキュリティを強化するために、次のクッキーオプションを設定します。 + +* `secure` - HTTPS経由でのみCookieを送信できるようにします。 +* `httpOnly` - CookieがクライアントJavaScriptではなくHTTP(S)上でのみ送信されることを保証し、クロスサイトスクリプティング攻撃から保護します。 +* `domain` - Cookie のドメインを示します。URL がリクエストされているサーバーのドメインと比較するために使用します。 一致する場合は、次にパス属性を確認します。 +* `path` - クッキーのパスを示します。リクエストパスと比較するために使用します。 これとドメインが一致した場合は、リクエストにクッキーを送信します。 +* `expires` - 永続的クッキーの有効期限を設定するために使用します。 + +[cookie-session](https://www.npmjs.com/package/cookie-session) ミドルウェアを使用した例を以下に示します。 + +```js +const session = require('cookie-session'); +const express = require('express'); +const app = express(); + +const expiryDate = new Date(Date.now() + 60 * 60 * 1000); // 1 hour +app.use( + session({ + name: 'session', + keys: ['key1', 'key2'], + cookie: { + secure: true, + httpOnly: true, + domain: 'example.com', + path: 'foo/bar', + expires: expiryDate, + }, + }) +); +``` + +## 承認に対するブルートフォース攻撃を防止 + +プライベートデータをより安全にするために、ログインエンドポイントが保護されていることを確認してください。 + +シンプルで強力な手法は、2つの指標を使用して認証試行をブロックすることです。 + +1. 同じユーザー名とIPアドレスによる連続失敗回数。 +2. 長期間IPアドレスからの失敗回数。 たとえば、1 日で 100 回失敗した場合、IP アドレスをブロックします。 + +[rate-limiter-flexible](https://github.com/animir/node-rate-limiter-flexible) パッケージは、このテクニックを簡単かつ高速にするためのツールを提供します。 You can find [an example of brute-force protection in the documentation](https://github.com/animir/node-rate-limiter-flexible/wiki/Overall-example#login-endpoint-protection) + +## 依存関係が安全であることを確認する + +npm を使用してアプリケーションの依存関係を管理するのは強力で便利です。 ただし、使用するパッケージには、アプリケーションにも影響を与える可能性のある重大なセキュリティ脆弱性が含まれている場合があります。 アプリのセキュリティは、依存関係の「最も弱いリンク」と同じくらい強力です。 + +npm@6 以降、npm は自動的にすべてのインストール リクエストをレビューします。 また、`npm audit` を使用して依存関係のツリーを分析することもできます。 + +```bash +$ npm audit +``` + +もっと安全な場合は、 [Snyk](https://snyk.io/) を検討してください。 + +Snyk は [コマンド ライン ツール](https://www.npmjs.com/package/snyk) と [Github 統合] (https://snyk.io/docs/github) の両方を提供しており、依存関係の既知の脆弱性についてアプリケーションを [Snyk のオープン ソース 脆弱性 データベース](https://snyk.io/vuln/) でチェックします。 CLI を以下のようにインストールします。 + +```bash +$ npm install -g snyk +$ cd your-app +``` + +このコマンドを使用して、アプリケーションの脆弱性をテストします。 + +```bash +$ snyk test +``` + +### その他の既知の脆弱性を回避する + +Keep an eye out for [Node Security Project](https://npmjs.com/advisories) or [Snyk](https://snyk.io/vuln/) advisories that may affect Express or other modules that your app uses. 一般的に、これらのデータベースは、Node セキュリティに関する知識とツールのための優れたリソースです。 + +Finally, Express apps—like any other web apps—can be vulnerable to a variety of web-based attacks. Familiarize yourself with known [web vulnerabilities](https://www.owasp.org/www-project-top-ten/) and take precautions to avoid them. + +## その他の考慮事項 + +優れた [Node.js セキュリティ チェックリスト](https://blog.risingstack.com/node-js-security-checklist/) からのさらなる推奨事項をいくつか紹介します。 これらの推奨事項の詳細については、そのブログ記事を参照してください。 + +* クロスサイト・スクリプティング(XSS)やコマンドインジェクション攻撃から保護するため、常にユーザー入力をフィルタリングしてサニタイズします。 +* パラメータ化されたクエリまたは準備された文を使用してSQLインジェクション攻撃を防御します。 +* アプリケーションのSQLインジェクションの脆弱性を検出するには、オープンソースの [sqlmap](http://sqlmap.org/)ツールを使用してください。 +* SSL暗号の設定をテストするには、 [nmap](https://nmap.org/) と [sslyze](https://github.com/nabla-c0d3/sslyze) ツールを使用します。 キー、再ネゴシエーション、および証明書の有効性。 +* [safe-regex](https://www.npmjs.com/package/safe-regex) を使用して、正規表現が [正規表現 サービス妨害](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) 攻撃の影響を受けないようにしましょう。 + +[helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/ja/advanced/healthcheck-graceful-shutdown.md b/src/content/pages/ja/advanced/healthcheck-graceful-shutdown.md new file mode 100644 index 0000000000..6611117c3a --- /dev/null +++ b/src/content/pages/ja/advanced/healthcheck-graceful-shutdown.md @@ -0,0 +1,28 @@ +--- +title: 健康チェックと優雅な閉鎖 +description: Expressアプリケーションでヘルスチェックと優雅なシャットダウンを実装して、信頼性を高め、デプロイメントを管理し、Kubernetesのようなロードバランサと統合する方法を学びます。 +--- + +## 優雅な停止 + +アプリケーションの新しいバージョンをデプロイする場合は、以前のバージョンを置き換える必要があります。 使用しているプロセスマネージャーは、最初にアプリケーションにSIGTERM信号を送信し、それが終了することを通知します。 アプリケーションがこのシグナルを取得したら、新しいリクエストの受け付けを停止し、継続中のリクエストをすべて終了する必要があります。 データベース接続とファイルロックを含む、使用するリソースをクリーンアップし、終了します。 + +### 例 + +```js +const server = app.listen(port); + +process.on('SIGTERM', () => { + debug('SIGTERM signal received: closing HTTP server'); + server.close(() => { + debug('HTTP server closed'); + }); +}); +``` + +## 健康チェック + +ロードバランサは、ヘルスチェックを使用して、アプリケーションインスタンスが健全かどうかを判断し、リクエストを受け入れることができます。 例えば、[Kubernetes には2つのヘルスチェックがあります](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/): + +- `liveness` コンテナを再起動するタイミングを決定します。 +- コンテナがいつトラフィックを受け入れる準備ができているかを決める準備が整います。 ポッドの準備ができていない場合は、サービスロードバランサーから取り外されます。 diff --git a/src/content/pages/ja/advanced/security-updates.mdx b/src/content/pages/ja/advanced/security-updates.mdx new file mode 100644 index 0000000000..adb45bfb10 --- /dev/null +++ b/src/content/pages/ja/advanced/security-updates.mdx @@ -0,0 +1,87 @@ +--- +title: セキュリティの更新 +description: 様々なバージョンの脆弱性リストを含む、Express.jsの最新のセキュリティアップデートとパッチを確認し、セキュアなアプリケーションを維持します。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Node.js の脆弱性は Express に直接影響します。 そのため、Node.js +脆弱性を監視する と最新の +安定版の Node.js を使用していることを確認してください。 + + + +以下のリストは、指定されたバージョンアップで修正された Express の脆弱性を列挙しています。 + + + +Express でセキュリティ上の脆弱性を発見したと思われる場合は、Security +ポリシーと手順をご覧ください。 + + + +## 4.x + +* 4.21.2 + * 依存関係の `path-to-regexp` が [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w) に対応するように更新されました。 +* 4.21.1 + * 依存関係の `cookie` が [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x) アドレスに更新されました。`res.cookie` を使用すると、アプリケーションに影響する可能性があります。 +* 4.20.0 + * `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796))におけるXSSの脆弱性の修正。 + * 依存関係の `serve-static` が [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p) に更新されました。 + * 依存関係の `send` が [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg) に更新されました。 + * 依存関係の `path-to-regexp` が [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j) に対応するように更新されました。 + * 依存関係の `body-parser` が [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7) を追加するように更新されました。これはURLエンコンデーションが有効になっている場合、アプリケーションに影響する可能性があります。 +* 4.19.0, 4.19.1 + * `res.location` と `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)のオープンリダイレクトの脆弱性を修正しました。 +* 4.17.3 + * 依存関係の `qs` が [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp) に更新されました。 `req.query`、`req.body`、`req.param`という以下のAPIを使用すると、アプリケーションに影響を与える可能性があります。 +* 4.16.0 + * 依存関係の `forwarded` が [vulnerability](https://npmjs.com/advisories/527) に更新されました。 以下の API が使用されている場合、アプリケーションに影響を与える可能性があります: `req.host` 、 `req.hostname` 、 `req.ips` 、 `req.protocol` 。 + * 依存関係の `mime` が [vulnerability](https://npmjs.com/advisories/535) 宛先に更新されましたが、この問題は Express には影響しません。 + * 依存関係の `send` が更新され、[Node.js 8.5.0 脆弱性](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/)に対する保護が提供されました。 これは、Express が特定の Node.js バージョン 8.5.0 で実行されることにのみ影響します。 +* 4.15.5 + * 依存関係の `debug` が [vulnerability](https://snyk.io/vuln/npm:debug:20170905) アドレスに更新されましたが、この問題は Express には影響しません。 + * 依存関係の `fresh` が [vulnerability](https://npmjs.com/advisories/526) に更新されました。 `express.static` 、 `req.fresh` 、 `res.json` 、 `res.json` 、 `res.send` 、 `res.send` 、 `res.sendFile` 、 `res.sendFile` 、 `res.sendStatus` などのAPIが使用されると、アプリケーションに影響します。 +* 4.15.3 + * 依存関係の `ms` が [vulnerability](https://snyk.io/vuln/npm:ms:20170412) に更新されました。 信頼されていない文字列が次の API で `maxAge` オプションに渡されると、アプリケーションに影響を与える可能性があります。`express.static` 、 `res.sendfile` 、 `res.sendFile` です。 +* 4.15.2 + * 依存関係`qs`が [vulnerability]（https://snyk.io/vuln/npm:qs:20170213）アドレスに更新されましたが、この問題はExpressには影響しません。 4.15.2 へのアップデートは良い方法ですが、脆弱性に対処する必要はありません。 +* 4.11.1 + * `express.static`、`res.sendfile`、`res.sendFile`におけるルートパス開示の脆弱性を修正しました。 +* 4.10.7 + * `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)のオープンリダイレクトの脆弱性を修正しました。 +* 4.8.8 + * `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)のディレクトリトラバーサルの脆弱性を修正しました。 +* 4.8.4 + * Node.js 0.10 は、`express.static` と `res.sendfile` に影響を与える特定の状況で `fd` をリークできます。 悪意のある要求は`fd`がリークし、最終的には`EMFILE`エラーとサーバーの応答性が低下する可能性があります。 +* 4.8.0 + * クエリ文字列に非常に高いインデックスを持つ疎行列は、プロセスがメモリ不足になり、サーバーがクラッシュする可能性があります。 + * 非常にネストされたクエリ文字列オブジェクトは、プロセスをブロックし、サーバーが一時的に応答しないようにする可能性があります。 + +## 3.x + + +**エクスプレス 3.x is END-OF-LIFE and no longer maintained** + +3.x における既知のセキュリティとパフォーマンスの問題は、前回のアップデート(2015年8月1日)から解決されていません。 最新版のExpressをご利用いただくことを強くお勧めします。 + +3.x以降のアップグレードができない場合は、[Commercial Support Options](/en/support#commercial-support-options)をご検討ください。 + + + +* 3.19.1 + * `express.static`、`res.sendfile`、`res.sendFile`におけるルートパス開示の脆弱性を修正しました。 +* 3.19.0 + * `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)のオープンリダイレクトの脆弱性を修正しました。 +* 3.16.10 + * `express.static`におけるディレクトリトラバーサルの脆弱性を修正しました。 +* 3.16.6 + * Node.js 0.10 は、`express.static` と `res.sendfile` に影響を与える特定の状況で `fd` をリークできます。 悪意のある要求は`fd`がリークし、最終的には`EMFILE`エラーとサーバーの応答性が低下する可能性があります。 +* 3.16.0 + * クエリ文字列のインデックスが非常に高いスパース配列は、プロセスがメモリ不足になり、サーバーがクラッシュする可能性があります。 + * 非常にネストされたクエリ文字列オブジェクトは、プロセスをブロックし、サーバーが一時的に応答しないようにする可能性があります。 +* 3.3.0 + * サポートされていないメソッドのオーバーライドを試みた 404 応答は、クロスサイトスクリプティング攻撃の影響を受けやすくなりました。 diff --git a/src/content/pages/ja/guide/database-integration.mdx b/src/content/pages/ja/guide/database-integration.mdx new file mode 100644 index 0000000000..e091ca9acf --- /dev/null +++ b/src/content/pages/ja/guide/database-integration.mdx @@ -0,0 +1,503 @@ +--- +title: データベースの統合 +description: MongoDB、MySQL、PostgreSQLなどのセットアップ例を含む、様々なデータベースを Express.js アプリケーションに統合する方法をご覧ください。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Expressアプリケーションにデータベースを接続する機能を追加することは、アプリケーション内のデータベースに適切なNode.jsドライバをロードするだけです。 このドキュメントでは、Express アプリケーションで最も人気のある Node.js モジュールのいくつかを追加して使用する方法を簡単に説明します。 + +* [Cassandra](#cassandra) +* [Couchbase](#couchbase) +* [CouchDB](#couchdb) +* [LevelDB](#leveldb) +* [MySQL](#mysql) +* [MongoDB](#mongodb) +* [Neo4j](#neo4j) +* [Oracle](#oracle) +* [PostgreSQL](#postgresql) +* [Redis](#redis) +* [SQL Server](#sql-server) +* [SQLite](#sqlite) +* [Elasticsearch](#elasticsearch) + + + +これらのデータベースドライバは、利用可能な多くの中にあります。 その他のオプションについては、 +[npm](https://www.npmjs.com/) サイトを検索してください。 + + + +## Cassandra + +**モジュール**: [cassandra-driver](https://github.com/datastax/nodejs-driver) + +### インストール + +```bash +$ npm install cassandra-driver +``` + +### 例 + +```js +const cassandra = require('cassandra-driver'); +const client = new cassandra.Client({ contactPoints: ['localhost'] }); + +client.execute('select key from system.local', (err, result) => { + if (err) throw err; + console.log(result.rows[0]); +}); +``` + +## Couchbase + +**モジュール**: [couchnode](https://github.com/couchbase/couchnode) + +### インストール + +```bash +$ npm install couchbase +``` + +### 例 + +```js +const couchbase = require('couchbase'); +const bucket = new couchbase.Cluster('http://localhost:8091').openBucket('bucketName'); + +// add a document to a bucket +bucket.insert('document-key', { name: 'Matt', shoeSize: 13 }, (err, result) => { + if (err) { + console.log(err); + } else { + console.log(result); + } +}); + +// get all documents with shoe size 13 +const n1ql = 'SELECT d.* FROM `bucketName` d WHERE shoeSize = $1'; +const query = N1qlQuery.fromString(n1ql); +bucket.query(query, [13], (err, result) => { + if (err) { + console.log(err); + } else { + console.log(result); + } +}); +``` + +## CouchDB + +**モジュール**: [nano](https://github.com/dscape/nano) + +### インストール + +```bash +$ npm install nano +``` + +### 例 + +```js +const nano = require('nano')('http://localhost:5984'); +nano.db.create('books'); +const books = nano.db.use('books'); + +// Insert a book document in the books database +books.insert({ name: 'The Art of war' }, null, (err, body) => { + if (err) { + console.log(err); + } else { + console.log(body); + } +}); + +// Get a list of all books +books.list((err, body) => { + if (err) { + console.log(err); + } else { + console.log(body.rows); + } +}); +``` + +## LevelDB + +**モジュール**: [levelup](https://github.com/rvagg/node-levelup) + +### インストール + +```bash +$ npm install level levelup leveldown +``` + +### 例 + +```js +const levelup = require('levelup'); +const db = levelup('./mydb'); + +db.put('name', 'LevelUP', (err) => { + if (err) return console.log('Ooops!', err); + + db.get('name', (err, value) => { + if (err) return console.log('Ooops!', err); + + console.log(`name=${value}`); + }); +}); +``` + +## MySQL + +**モジュール**: [mysql](https://github.com/felixge/node-mysql/) + +### インストール + +```bash +$ npm install mysql +``` + +### 例 + +```js +const mysql = require('mysql'); +const connection = mysql.createConnection({ + host: 'localhost', + user: 'dbuser', + password: 's3kreee7', + database: 'my_db', +}); + +connection.connect(); + +connection.query('SELECT 1 + 1 AS solution', (err, rows, fields) => { + if (err) throw err; + + console.log('The solution is: ', rows[0].solution); +}); + +connection.end(); +``` + +## MongoDB + +**モジュール**: [mongodb](https://github.com/mongodb/node-mongodb-native) + +### インストール + +```bash +$ npm install mongodb +``` + +### 例 (v2.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { + if (err) throw err; + + db.collection('mammals') + .find() + .toArray((err, result) => { + if (err) throw err; + + console.log(result); + }); +}); +``` + +### 例 (v3.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, client) => { + if (err) throw err; + + const db = client.db('animals'); + + db.collection('mammals') + .find() + .toArray((err, result) => { + if (err) throw err; + + console.log(result); + }); +}); +``` + +MongoDB用のオブジェクトモデルドライバが必要な場合は、 [Mongoose](https://github.com/LearnBoost/mongoose) を参照してください。 + +## Neo4j + +**モジュール**: [neo4j-driver](https://github.com/neo4j/neo4j-javascript-driver) + +### インストール + +```bash +$ npm install neo4j-driver +``` + +### 例 + +```js +const neo4j = require('neo4j-driver'); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth.basic('neo4j', 'letmein')); + +const session = driver.session(); + +session.readTransaction((tx) => { + return tx + .run('MATCH (n) RETURN count(n) AS count') + .then((res) => { + console.log(res.records[0].get('count')); + }) + .catch((error) => { + console.log(error); + }); +}); +``` + +## Oracle + +**モジュール**: [oracledb](https://github.com/oracle/node-oracledb) + +### インストール + +注意: [インストール前提条件を参照](https://github.com/oracle/node-oracledb#-installation)。 + +```bash +$ npm install oracledb +``` + +### 例 + +```js +const oracledb = require('oracledb'); +const config = { + user: '', + password: '', + connectString: 'localhost:1521/orcl', +}; + +async function getEmployee(empId) { + let conn; + + try { + conn = await oracledb.getConnection(config); + + const result = await conn.execute('select * from employees where employee_id = :id', [empId]); + + console.log(result.rows[0]); + } catch (err) { + console.log('Ouch!', err); + } finally { + if (conn) { + // conn assignment worked, need to close + await conn.close(); + } + } +} + +getEmployee(101); +``` + +## PostgreSQL + +**モジュール**: [pg-promise](https://github.com/vitaly-t/pg-promise) + +### インストール + +```bash +$ npm install pg-promise +``` + +### 例 + +```js +const pgp = require('pg-promise')(/* options */); +const db = pgp('postgres://username:password@host:port/database'); + +db.one('SELECT $1 AS value', 123) + .then((data) => { + console.log('DATA:', data.value); + }) + .catch((error) => { + console.log('ERROR:', error); + }); +``` + +## Redis + +**モジュール**: [redis](https://github.com/mranney/node_redis) + +### インストール + +```bash +$ npm install redis +``` + +### 例 + +```js +const redis = require('redis'); +const client = redis.createClient(); + +client.on('error', (err) => { + console.log(`Error ${err}`); +}); + +client.set('string key', 'string val', redis.print); +client.hset('hash key', 'hashtest 1', 'some value', redis.print); +client.hset(['hash key', 'hashtest 2', 'some other value'], redis.print); + +client.hkeys('hash key', (err, replies) => { + console.log(`${replies.length} replies:`); + + replies.forEach((reply, i) => { + console.log(` ${i}: ${reply}`); + }); + + client.quit(); +}); +``` + +## SQL Server + +**モジュール**: [tedious](https://github.com/tediousjs/tedious) + +### インストール + +```bash +$ npm install tedious +``` + +### 例 + +```js +const Connection = require('tedious').Connection; +const Request = require('tedious').Request; + +const config = { + server: 'localhost', + authentication: { + type: 'default', + options: { + userName: 'your_username', // update me + password: 'your_password', // update me + }, + }, +}; + +const connection = new Connection(config); + +connection.on('connect', (err) => { + if (err) { + console.log(err); + } else { + executeStatement(); + } +}); + +function executeStatement() { + request = new Request("select 123, 'hello world'", (err, rowCount) => { + if (err) { + console.log(err); + } else { + console.log(`${rowCount} rows`); + } + connection.close(); + }); + + request.on('row', (columns) => { + columns.forEach((column) => { + if (column.value === null) { + console.log('NULL'); + } else { + console.log(column.value); + } + }); + }); + + connection.execSql(request); +} +``` + +## SQLite + +**モジュール**: [sqlite3](https://github.com/mapbox/node-sqlite3) + +### インストール + +```bash +$ npm install sqlite3 +``` + +### 例 + +```js +const sqlite3 = require('sqlite3').verbose(); +const db = new sqlite3.Database(':memory:'); + +db.serialize(() => { + db.run('CREATE TABLE lorem (info TEXT)'); + const stmt = db.prepare('INSERT INTO lorem VALUES (?)'); + + for (let i = 0; i < 10; i++) { + stmt.run(`Ipsum ${i}`); + } + + stmt.finalize(); + + db.each('SELECT rowid AS id, info FROM lorem', (err, row) => { + console.log(`${row.id}: ${row.info}`); + }); +}); + +db.close(); +``` + +## Elasticsearch + +**モジュール**: [elasticsearch](https://github.com/elastic/elasticsearch-js) + +### インストール + +```bash +$ npm install elasticsearch +``` + +### 例 + +```js +const elasticsearch = require('elasticsearch'); +const client = elasticsearch.Client({ + host: 'localhost:9200', +}); + +client + .search({ + index: 'books', + type: 'book', + body: { + query: { + multi_match: { + query: 'express js', + fields: ['title', 'description'], + }, + }, + }, + }) + .then( + (response) => { + const hits = response.hits.hits; + }, + (error) => { + console.trace(error.message); + } + ); +``` diff --git a/src/content/pages/ja/guide/migrating-4.mdx b/src/content/pages/ja/guide/migrating-4.mdx new file mode 100644 index 0000000000..f726677799 --- /dev/null +++ b/src/content/pages/ja/guide/migrating-4.mdx @@ -0,0 +1,662 @@ +--- +title: Express 4に移動中 +description: Express.jsアプリケーションをバージョン3からバージョン4に移行するためのガイドでは、ミドルウェアの変更、ルーティング、コードベースの効果的な更新方法について説明します。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +エクスプレス4はエクスプレス3からの変更です。 つまり、Expressバージョンを依存関係で更新すると、既存のExpress 3アプリは動作しなくなります。 + +この記事のカバー： + + + +## Express 4の変更 + +Express 4にはいくつかの大きな変更点があります。 + + + +こちらもご参照ください: + +* [新機能 in 4.x] (https://github.com/expressjs/express/wiki/New-features-in-4.x) +* [Migrating from 3.x to 4.x](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) + +### Express coreとミドルウェアシステムへの変更 + +Express 4はもうConnectに依存せず、組み込みの +ミドルウェアをコアから削除します。ただし、`express.static`関数は除外します。 This means that +Express is now an independent routing and middleware web framework, and +Express versioning and releases are not affected by middleware updates. + +組み込みのミドルウェアがなければ、アプリケーションの実行に必要なすべての +ミドルウェアを明示的に追加する必要があります。 以下の手順に従ってください： + +1. モジュールをインストール: `npm install --save \` +2. アプリでは、次のモジュールを必要とします: `require('module-name')` +3. ドキュメントに従ってモジュールを使用します: `app.use( ... )` + +以下の表は、Express 4でのExpress 3ミドルウェアとそのミドルウェアを示しています。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
エクスプレス 3エクスプレス 4
+ express.bodyParser + + body-parser + + multer +
+ express.compress + + 圧縮 +
+ express.cookieSession + + クッキーセッション +
+ express.cookieParser + + クッキーパーサ +
+ express.logger + + モーガン +
+ express.session + + express-session +
+ express.favicon + + サービスファビコン +
+ express.responseTime + + 応答時間 +
+ express.errorHandler + + errorhandler +
+ express.methodOverride + + メソッド-オーバーライド +
+ express.timeout + + 接続タイムアウト +
+ express.vhost + + vhost +
+ express.csrf + + csurf +
+ express.directory + + サーブインデックス +
+ express.static + + スタティック +
+ +Here is the [complete list](https://github.com/senchalabs/connect#middleware) of Express 4 middleware. + +ほとんどの場合、古いバージョン3のミドルウェアを +のExpress 4に置き換えることができます。 詳細については、 +GitHub のモジュールドキュメントを参照してください。 + +#### `app.use`はパラメータを受け付けます + +バージョン 4 では、変数 parameter を使用して、ミドルウェア関数がロードされるパスを定義できます。 次に、ルートハンドラからパラメータの値を読み込みます。 +例: + +```js +app.use('/book/:id', (req, res, next) => { + console.log('ID:', req.params.id); + next(); +}); +``` + +### ルーティング システム + +Apps now implicitly load routing middleware, so you no longer have to +worry about the order in which middleware is loaded with respect to +the `router` middleware. + +ルートの定義方法は変更されていませんが、ルーティングシステムにはルートの整理に役立つ2つの +新機能があります。 + +* 新しいメソッド `app.route()` は、ルートパスに対してチェーン可能なルートハンドラを作成します。 +* モジュール式のマウント可能なルートハンドラを作成するための新しいクラス `express.Router` 。 + +#### `app.route()`メソッド + +新しい`app.route()`メソッドを使用すると、ルートパスのチェーン可能なルートハンドラ +を作成できます。 パスは単一の場所で指定されているため、モジュラールートを作成することは、冗長性とタイプミスを削減するのに役立ちます。 For more +information about routes, see [`Router()` documentation](/en/4x/api#router). + +以下は、`app.route()`関数を使用して定義されたルートハンドラの例です。 + +```js +app + .route('/book') + .get((req, res) => { + res.send('Get a random book'); + }) + .post((req, res) => { + res.send('Add a book'); + }) + .put((req, res) => { + res.send('Update the book'); + }); +``` + +#### `express.Router` クラス + +ルートを整理するのに役立つもう一つの機能は、新しいクラス +`express.Router` で、モジュラーマウント可能な +ルートハンドラを作成するために使用できます。 `Router`インスタンスは完全なミドルウェアと +ルーティングシステムです。このため、しばしば"mini-app"と呼ばれます。 + +The following example creates a router as a module, loads middleware in +it, defines some routes, and mounts it on a path on the main app. + +For example, create a router file named `birds.js` in the app directory, +with the following content: + +```js +var express = require('express'); +var router = express.Router(); + +// middleware specific to this router +router.use((req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}); +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +次に、アプリにルーターモジュールをロードします。 + +```js +var birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +The app will now be able to handle requests to the `/birds` and +`/birds/about` paths, and will call the `timeLog` +middleware that is specific to the route. + +### その他の変更 + +以下の表は、Express 4の他の重要な変更点を示しています。 + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
オブジェクト説明
Node.jsExpress 4 は Node.js 0.10.x 以降が必要で、Node.js 0.8.x のサポートを廃止しました。
`http.createServer()` + `http`モジュールは、 + （socket.io/SPDY/HTTPS）で直接動作する必要がない限り、もはや必要ありません。 アプリは、`app.listen()`関数を使用して起動できます。 +
`app.configure()` + `app.configure()`関数が削除されました。 `process.env.NODE_ENV` または + `app.get('env')` 関数を使用して環境を検出し、それに応じてアプリを構成します。 +
`json spaces` + Express 4では、`json spaces` アプリケーションプロパティはデフォルトで無効になっています。 +
`req.accepted()` + `req.accepts()`、`req.acceptsEncodings()`、`req.acceptsCharsets()`、および + `req.acceptsLanguages()`を使用してください。 +
`res.location()`相対URLを解決しなくなりました。
`req.params`配列で、現在はオブジェクトです。
`res.locals`関数でした; 今はオブジェクトです。
`res.headerSent``res.headersSent` に変更しました。
`app.route``app.mountpath` として利用可能になりました。
`res.on('header')`削除しました。
`res.charset`削除しました。
`res.setHeader('Set-Cookie', val)` + 機能は基本的なクッキー値の設定に限定されるようになりました。 追加された + 機能には、 `res.cookie()` を使用します。 +
+ +## アプリの移行例 + +Express 3アプリケーションをExpress 4に移行する例を以下に示します。 +関心のあるファイルは `app.js` と `package.json` です。 + +### バージョン3アプリ + +#### `app.js` + +次の `app.js` ファイルを含む Express v.3 アプリケーションを考えてみましょう。 + +```js +var express = require('express'); +var routes = require('./routes'); +var user = require('./routes/user'); +var http = require('http'); +var path = require('path'); + +var app = express(); + +// all environments +app.set('port', process.env.PORT || 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(express.favicon()); +app.use(express.logger('dev')); +app.use(express.methodOverride()); +app.use(express.session({ secret: 'your secret here' })); +app.use(express.bodyParser()); +app.use(app.router); +app.use(express.static(path.join(__dirname, 'public'))); + +// development only +if (app.get('env') === 'development') { + app.use(express.errorHandler()); +} + +app.get('/', routes.index); +app.get('/users', user.list); + +http.createServer(app).listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + +#### `package.json` + +The accompanying version 3 `package.json` file might look +something like this: + +```json +{ + "name": "application-name", + "version": "0.0.1", + "private": true, + "scripts": { + "start": "node app.js" + }, + "dependencies": { + "express": "3.12.0", + "pug": "*" + } +} +``` + +### プロセス + +以下のコマンドを使用して、 +Express 4アプリに必要なミドルウェアをインストールし、ExpressとPugを最新の +バージョンにアップデートして移行を開始します。 + +```bash +$ npm install serve-favicon morgan method-override express-session body-parser multer errorhandler express@latest --save +``` + +`app.js`に以下の変更を加えます。 + +1. 組み込みの Express ミドルウェア関数 `express.favicon` , + `express.logger` , `express.methodOverride` , + `express.session` , `express.bodyParser` と + `express.errorHandler` は、 + `express` オブジェクトでは使用できなくなりました。 代わりの + を手動でインストールし、アプリにロードする必要があります。 + +2. `app.router`関数をロードする必要がなくなりました。 + 有効なExpress 4アプリオブジェクトではないため、 + `app.use(app.router);` コードを削除します。 + +3. ミドルウェア関数が正しい順序でロードされていることを確認してください - アプリのルートをロードした後に `errorHandler` をロードします。 + +### バージョン4アプリ + +#### `package.json` + +上記の `npm` コマンドを実行すると、 `package.json` が以下のように更新されます。 + +```json +{ + "name": "application-name", + "version": "0.0.1", + "private": true, + "scripts": { + "start": "node app.js" + }, + "dependencies": { + "body-parser": "^1.5.2", + "errorhandler": "^1.1.1", + "express": "^4.8.0", + "express-session": "^1.7.2", + "pug": "^2.0.0", + "method-override": "^2.1.2", + "morgan": "^1.2.2", + "multer": "^0.1.3", + "serve-favicon": "^2.0.1" + } +} +``` + +#### `app.js` + +次に、無効なコードを削除し、必要なミドルウェアをロードし、必要に応じて他の +変更を行います。 `app.js`ファイルは次のようになります。 + +```js +var http = require('http'); +var express = require('express'); +var routes = require('./routes'); +var user = require('./routes/user'); +var path = require('path'); + +var favicon = require('serve-favicon'); +var logger = require('morgan'); +var methodOverride = require('method-override'); +var session = require('express-session'); +var bodyParser = require('body-parser'); +var multer = require('multer'); +var errorHandler = require('errorhandler'); + +var app = express(); + +// all environments +app.set('port', process.env.PORT || 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(favicon(path.join(__dirname, '/public/favicon.ico'))); +app.use(logger('dev')); +app.use(methodOverride()); +app.use( + session({ + resave: true, + saveUninitialized: true, + secret: 'uwotm8', + }) +); +app.use(bodyParser.json()); +app.use(bodyParser.urlencoded({ extended: true })); +app.use(multer()); +app.use(express.static(path.join(__dirname, 'public'))); + +app.get('/', routes.index); +app.get('/users', user.list); + +// error handling middleware should be loaded after the loading the routes +if (app.get('env') === 'development') { + app.use(errorHandler()); +} + +var server = http.createServer(app); +server.listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + + +`http` モジュール (socket.io/SPDY/HTTPS) で直接作業する必要がない限り、読み込みは必要ありません。この方法でアプリを起動できます。 + +```js +app.listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + + + +### アプリの実行 + +移行処理が完了し、アプリは +エクスプレス4アプリになりました。 確認するには、次のコマンドを使用してアプリを起動します。 + +```bash +$ node . +``` + +[http://localhost:3000](http://localhost:3000) +を読み込み、Express 4によってレンダリングされるホームページを参照してください。 + +## Express 4アプリジェネレーターへのアップグレード + +The command-line tool to generate an Express app is still +`express`, but to upgrade to the new version, you must uninstall +the Express 3 app generator and then install the new +`express-generator`. + +### インストール中 + +すでにExpress 3アプリジェネレータがシステムにインストールされている場合、 +アンインストールする必要があります。 + +```bash +$ npm uninstall -g express +``` + +ファイルとディレクトリ権限の設定に応じて、 +`sudo` でこのコマンドを実行する必要があります。 + +新しいジェネレータをインストールします。 + +```bash +$ npm install -g express-generator +``` + +ファイルとディレクトリ権限の設定に応じて、 +`sudo` でこのコマンドを実行する必要があります。 + +システムの `express` コマンドが +Express 4ジェネレータに更新されます。 + +### アプリジェネレーターの変更 + +コマンドオプションと使用方法は、以下の例外を除き、ほとんど同じままです。 + +* `--sessions` オプションを削除しました。 +* `--jshtml` オプションを削除しました。 +* [Hogan.js](http://twitter.github.io/hogan.js/) をサポートするための `--hogan` オプションを追加しました。 + +### 例 + +Express 4 アプリを作成するには、次のコマンドを実行します。 + +```bash +$ express app4 +``` + +If you look at the contents of the `app4/app.js` file, you will notice +that all the middleware functions (except `express.static`) that are required for +the app are loaded as independent modules, and the `router` middleware +is no longer explicitly loaded in the app. + +`app.js`ファイルがノードになっていることにも気づくでしょう。 sモジュールは、古いジェネレータによって生成されたスタンドアロンアプリとは対照的に。 + +依存関係をインストールした後、次のコマンドを使用してアプリを起動します。 + +```bash +$ npm start +``` + +If you look at the `npm start` script in the `package.json` file, +you will notice that the actual command that starts the app is +`node ./bin/www`, which used to be `node app.js` +in Express 3. + +Because the `app.js` file that was generated by the Express 4 generator +is now a Node.js module, it can no longer be started independently as an app +(unless you modify the code). モジュールは Node.js ファイル +にロードされ、Node.js ファイルを介して開始する必要があります。 Node.js ファイルは `./bin/www` +です。 + +Expressアプリの作成やアプリの起動には、`bin`ディレクトリも拡張機能のない`www` +ファイルも必須ではありません。 それらは +発電機による提案ですので、 +のニーズに合わせて変更してください。 + +To get rid of the `www` directory and keep things the "Express 3 way", +delete the line that says `module.exports = app;` at the end of the +`app.js` file, then paste the following code in its place: + +```js +app.set('port', process.env.PORT || 3000); + +var server = app.listen(app.get('port'), () => { + debug('Express server listening on port ' + server.address().port); +}); +``` + +`app.js`ファイルの先頭にある`debug`モジュールがロードされていることを確認します。 + +```js +var debug = require('debug')('app4'); +``` + +次に、 `start": `package.json` ファイル中の "node ./bin/www"` を `"start": "node app.js"` に変更します。 + +これで `./bin/www` の機能を +`app.js` に戻しました。 This change is not recommended, but the exercise helps you +to understand how the `./bin/www` file works, and why the `app.js` file +no longer starts on its own. diff --git a/src/content/pages/ja/guide/migrating-5.mdx b/src/content/pages/ja/guide/migrating-5.mdx new file mode 100644 index 0000000000..ce601d7d1b --- /dev/null +++ b/src/content/pages/ja/guide/migrating-5.mdx @@ -0,0 +1,678 @@ +--- +title: Express 5に移動中 +description: Express.jsアプリケーションをバージョン4からバージョン5に移行するための包括的なガイドで、破壊的な変更、非推奨のメソッド、および新たな改善が詳しく説明されています。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +エクスプレス5はエクスプレス4と大きく異なりません。 同じ基本APIを維持していますが、以前のバージョンとの互換性を破る変更はまだあります。 したがって、Express 5を使用するように更新すると、Express 4で構築されたアプリケーションが動作しない可能性があります。 + +このバージョンをインストールするには、Node.js バージョン 18 以上が必要です。 次に、アプリケーションディレクトリで次のコマンドを実行します。 + +```sh +npm install "express@5" +``` + +その後、自動テストを実行して何が失敗するかを確認し、以下に示すアップデートに従って問題を解決することができます。 テストに失敗した後、どのエラーが発生したかを確認するためにアプリケーションを実行します。 サポートされていないメソッドやプロパティを使用している場合は、すぐに確認できます。 + +## Express 5 Codemods + +エクスプレスサーバーを移行するのに役立ちます。 コードを自動的に最新バージョンの Express に更新するコードを作成しました。 + +使用可能なすべてのコードを実行するには、次のコマンドを実行します。 + +```sh +npx codemod@latest @expressjs/v5-migration-recipes +``` + +特定のコードを実行したい場合は、次のコマンドを実行できます。 + +```sh +npx codemod@latest @expressjs/name-of-the-codemod +``` + +利用可能なコードリスト [here](https://codemod.link/express) があります。 + +## Express 5の変更 + +**メソッドとプロパティを削除** + + + +**変更** + + + +**改善** + + + +## 削除されたメソッドとプロパティ + +これらのメソッドやプロパティをアプリケーションで使用すると、クラッシュします。 したがって、バージョン5にアップデートした後、アプリを変更する必要があります。 + +### app.del() + +Express 5では、`app.del()`関数がサポートされなくなりました。 この関数を使うと、エラーがスローされます。 HTTP DELETEルートを登録するには、代わりに`app.delete()`関数を使用します。 + +`delete`はJavaScriptで予約されているキーワードであるため、最初は`delete`の代わりに`del`が使用されていました。 しかし、ECMAScript 6 では、 `delete` などの予約キーワードをプロパティ名として使用することができます。 + + +非推奨の署名は次のコマンドで置き換えることができます: + +```plaintext +npx codemod@latest @expressjs/route-del-to-delete +``` + + + +```js +// v4 +app.del('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); + +// v5 +app.delete('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); +``` + +### app.param(fn) + +`app.param(fn)`署名は、`app.param(name, fn)`関数の動作を変更するために使用されました。 v4.11.0以降非推奨となり、Express 5では全くサポートされなくなりました。 + +### 複数化されたメソッド名 + +以下のメソッド名が複数化されています。 Express 4 では、古いメソッドを使用すると非推奨になりました。 Express 5ではサポートされていません： + +`req.acceptsCharset()`は`req.acceptsCharsets()`に置き換えられます。 + +`req.acceptsEncoding()`は`req.acceptsEncodings()`に置き換えられます。 + +`req.acceptsLanguage()`は`req.acceptsLanguages()`に置き換えられました。 + + +非推奨の署名は次のコマンドで置き換えることができます: + +```plaintext +npx codemod@latest @expressjs/pluralize-method-names +``` + + + +```js +// v4 +app.all('/', (req, res) => { + req.acceptsCharset('utf-8'); + req.acceptsEncoding('br'); + req.acceptsLanguage('en'); + + // ... +}); + +// v5 +app.all('/', (req, res) => { + req.acceptsCharsets('utf-8'); + req.acceptsEncodings('br'); + req.acceptsLanguages('en'); + + // ... +}); +``` + +### app.param(name, fn) の名前の先頭コロン (:) + +\`appの名前の先頭にあるコロン文字 (:) です。 aram(name, fn)関数はExpress 3の名残であり、後方互換性のため、Express 4は廃止予定の通知でサポートしています。 Express 5は黙って無視し、コロンをつけずに名前パラメータを使用します。 + +Express 4 の [app.param](/en/4x/api#app.param) のドキュメントに従っている場合、これはあなたのコードには影響しません。 主要な結腸については言及していません + +### req.param(name) + +これは、潜在的に混乱し、フォームデータを取得する危険な方法が削除されました。 ここで、`req.params`、`req.body`、または`req.query`オブジェクトの中で、送信されたパラメータ名を具体的に探す必要があります。 + + +非推奨の署名は次のコマンドで置き換えることができます: + +```plaintext +npx codemod@latest @expressjs/explicit-request-params +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + const id = req.param('id'); + const body = req.param('body'); + const query = req.param('query'); + + // ... +}); + +// v5 +app.post('/user', (req, res) => { + const id = req.params.id; + const body = req.body; + const query = req.query; + + // ... +}); +``` + +### res.json(obj, status) + +Express 5 では署名 `res.json(obj, status)` がサポートされなくなりました。 代わりに、ステータスを設定し、 `res.json()` メソッドに次のようにチェーンさせます。`res.status(status).json(obj)` 。 + + +非推奨の署名は次のコマンドで置き換えることができます: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.json({ name: 'Ruben' }, 201); +}); + +// v5 +app.post('/user', (req, res) => { + res.status(201).json({ name: 'Ruben' }); +}); +``` + +### res.jsonp(obj, status) + +Express 5 では署名 `res.jsonp(obj, status)` がサポートされなくなりました。 代わりに、ステータスを設定し、 `res.jsonp()` メソッドを次のようにチェーンします。`res.status(status).jsonp(obj)` 。 + + +非推奨の署名は次のコマンドで置き換えることができます: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.jsonp({ name: 'Ruben' }, 201); +}); + +// v5 +app.post('/user', (req, res) => { + res.status(201).jsonp({ name: 'Ruben' }); +}); +``` + +### res.redirect(url, status) + +Express 5 では署名 `res.redirect(url, status)` がサポートされなくなりました。 代わりに、`res.redirect(status, url)` という署名を使用します。 + + +非推奨の署名は次のコマンドで置き換えることができます: + +```plaintext +npx codemod@latest @expressjs/redirect-arg-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('/users', 301); +}); + +// v5 +app.get('/user', (req, res) => { + res.redirect(301, '/users'); +}); +``` + +### res.redirect('back') と res.location('back') + +Express 5では、`res.redirect()`と`res.location()`メソッドの魔法文字列`back`がサポートされなくなりました。 代わりに、 `req.get('Referrer') |'/'`の値を使用して前のページにリダイレクトします。 Express 4 では、`res.redirect('back')` と `res.location('back')` メソッドは廃止されました。 + + +非推奨の署名は次のコマンドで置き換えることができます: + +```plaintext +npx codemod@latest @expressjs/back-redirect-deprecated +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('back'); +}); + +// v5 +app.get('/user', (req, res) => { + res.redirect(req.get('Referrer') || '/'); +}); +``` + +### res.send(body, status) + +Express 5 では署名 `res.send(obj, status)` がサポートされなくなりました。 代わりに、ステータスを設定し、 `res.status(status).send(obj)` のように、 `res.send()` メソッドを連鎖させます。 + + +非推奨の署名は次のコマンドで置き換えることができます: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send({ name: 'Ruben' }, 200); +}); + +// v5 +app.get('/user', (req, res) => { + res.status(200).send({ name: 'Ruben' }); +}); +``` + +### res.send(status + +Express 5では、`status` が数値である署名 `res.send(status)` がサポートされなくなりました。 代わりに、 `res を使ってください。 endStatus(statusCode)` 関数は、HTTP レスポンスヘッダーのステータスコードを設定し、コードのテキストバージョンを送信します。 "Not Found", "Internal Server Error"など。 +\`res を使って数字を送る必要がある場合。 end()関数は、数字を文字列に変換するために引用符で囲みます Expressはサポートされていない古い署名を使用しようとしないようにします。 + + +非推奨の署名は次のコマンドで置き換えることができます: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send(200); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendStatus(200); +}); +``` + +### res.sendfile() + +`res.sendfile()`関数は、Express 5でキャメルケースのバージョン`res.sendFile()`に置き換えられました。 + +**注意:** Express 5, `res. endFile()`は、MIME タイプの検出に`mime-types`パッケージを使用します。これは、一般的なファイルタイプの場合、Express 4とは異なるContent-Type値を返します。 + +* JavaScriptファイル (.js): 「application/javascript」の代わりに「text/javascript」を追加しました +* JSON ファイル (.json): 「text/json」の代わりに「application/json」になりました +* CSS ファイル (.css): "text/plain" ではなく "text/css" になりました +* XML ファイル (.xml): "text/xml" の代わりに "application/xml" になりました +* フォントファイル (.woff): "application/font-woff" ではなく "font/woff" になりました +* SVG ファイル (.svg): "application/svg+xml" の代わりに "image/svg+xml" になりました + + +非推奨の署名は次のコマンドで置き換えることができます: + +```plaintext +npx codemod@latest @expressjs/camelcase-sendfile +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.sendfile('/path/to/file'); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendFile('/path/to/file'); +}); +``` + +### router.param(fn) + +`router.param(fn)`署名は、`router.param(name, fn)`関数の動作を変更するために使用されました。 v4.11.0以降非推奨となり、Express 5では全くサポートされなくなりました。 + +### express.static.mime + +Express 5 では、`mime` は `static` フィールドのエクスポートされたプロパティではなくなりました。 +MIME タイプの値を扱うには、[`mime-types` package](https://github.com/jshttp/mime-types) を使用します。 + +**重要:** この変更は `express.static.mime` の直接使用だけでなく、 `res.sendFile()` のような MIME タイプの検出に依存する Express メソッドにも影響します。 Express 4から次のMIMEタイプが変更されました。 + +* JavaScriptファイル (.js): 「application/javascript」の代わりに「text/javascript」として提供されるようになりました +* JSON ファイル (.json): 「text/json」の代わりに「application/json」として提供されるようになりました +* CSS ファイル (.css): 「text/plain」の代わりに「text/css」として提供されるようになりました +* HTML ファイル (): 単に "text/html" の代わりに "text/html; charset=utf-8" として提供されました +* XML ファイル (.xml): "text/xml" の代わりに "application/xml" として提供されるようになりました +* フォント ファイル (.woff): "application/font-woff" ではなく "font/woff" として提供されるようになりました + +```js +// v4 +express.static.mime.lookup('json'); + +// v5 +const mime = require('mime-types'); +mime.lookup('json'); +``` + +### express:routerデバッグログ + +Express 5では、ルータの処理ロジックは依存関係によって実行されます。 したがって、ルーターの +デバッグログは、`express::` 名前空間で使用できなくなります。 +v4 では、`express:router` 、 `express:router:layer` 、 +および `express:router:route` の下でログを利用できました。 これらはすべて `express:*` という名前空間の下に含まれています。 +v5.1以降では、ログは名前空間`router`、`router:layer`、および`router:route`の下で利用できます。 +`router:layer` と `router:route` のログは、名前空間の `router:*` に含まれています。 +v4 で `express:*` を使用してデバッグログの詳細を達成するには、 +`express:*` 、 `router`、 `router:*` を使用します。 + +```sh + +DEBUG=express:* node index.js + + +DEBUG=express:*,router,router:* node index.js +``` + +## 変更済み + +### パス経路一致の構文 + +パスルートマッチング構文は、文字列が`app.all()`、`app.use()`、`app.METHOD()`、`router.all()`、`router.METHOD()`、`router.METHOD()`、`router.METHOD()`、`router.use()` APIに最初のパラメータとして与えられた場合です。 パス文字列が受信リクエストと一致する方法を次のように変更しました: + +* ワイルドカード`*`には名前が必要です。パラメータ`:`の動作に一致します。`/*`の代わりに`/*splat`を使用します。 + +```js +// v4 +app.get('/*', async (req, res) => { + res.send('ok'); +}); + +// v5 +app.get('/*splat', async (req, res) => { + res.send('ok'); +}); +``` + + +`*spat` はルートパスのないパスにマッチします。 `/`と同様にルートパスをマッチさせる必要がある場合は、 `/{*spat}`を使用し、ワイルドカードを括弧で囲みます。 + +```js +// v5 +app.get('/{*splat}', async (req, res) => { + res.send('ok'); +}); +``` + + + +* オプションの文字 `?` はサポートされなくなりました。代わりに括弧を使用してください。 + +```js +// v4 +app.get('/:file.:ext?', async (req, res) => { + res.send('ok'); +}); + +// v5 +app.get('/:file{.:ext}', async (req, res) => { + res.send('ok'); +}); +``` + +* 正規表現文字はサポートされていません。 例: + +```js +app.get('/[discussion|page]/:slug', async (req, res) => { + res.status(200).send('ok'); +}); +``` + +次に変更する必要があります： + +```js +app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { + res.status(200).send('ok'); +}); +``` + +* いくつかの文字はアップグレード中に混乱を避けるために予約されています (`()[]?+!`), それらをエスケープするために`\`を使用します。 +* パラメータ名が有効な JavaScript 識別子をサポートするようになりました。また、`:"this"` のように引用符で囲まれました。 + +### ミドルウェアとハンドラーから取り扱われる拒否された約束。 + +rejected promiseを返すリクエストミドルウェアとハンドラは、「Error」として拒否された値をエラー処理ミドルウェアに転送することで処理されるようになりました。 つまり、 `async` 関数をミドルウェアとして、ハンドラを使うのはこれまで以上に簡単です。 `async` 関数でエラーがスローされるか、拒否された Promise が async 関数内で `await`ed になります。 これらのエラーは、`next(err)`を呼び出すかのようにエラーハンドラに渡されます。 + +Express でのエラー処理の詳細については、[Error handling documentation](/en/guide/error-handling)を参照してください。 + +### express.urlencoded + +`express.urlencoded` メソッドはデフォルトで `extended` オプション `false` を設定します。 + +### express.static dotfiles + +Express 5では、`express.static` ミドルウェアの `dotfiles` オプションがデフォルトで `"ignore"` になりました。 これは、デフォルトでdotfilesが提供されたExpress 4からの変更です。 結果として、`のようにドット(`.`)で始まるディレクトリ内のファイル。 ell-known`はアクセスできなくなり、**404 Not Found**エラーが返されます。 これにより、Android App LinksやApple Universal Linksなどのドットディレクトリの提供に依存する機能が壊れる可能性があります。 + +破壊コードの例: + +```js +// v4 +app.use(express.static('public')); +``` + +Express 5に移行した後、`/.well-known/assetlinks.json`へのリクエストは**404 Not Found**になります。 + +これを修正するには、`dotfiles: "allow"` オプションを使用して特定のドットディレクトリを指定します。 + +```js +// v5 +app.use('/.well-known', express.static('public/.well-known', { dotfiles: 'allow' })); +app.use(express.static('public')); +``` + +このアプローチにより、意図したドットディレクトリのみを安全に提供し、他のdotfilesのデフォルトの安全な動作を維持することができます。 + +### app.listen + +Express 5 では、サーバーがエラーイベントを受信したときに `app.listen` メソッドがユーザーが提供するコールバック関数を呼び出します。 Express 4では、そのようなエラーがスローされます。 この変更により、エラー処理の責任が Express 5 のコールバック関数に移行されます。 エラーがある場合は、コールバックに引数として渡されます。 +例: + +```js +const server = app.listen(8080, '0.0.0.0', (error) => { + if (error) { + throw error; // e.g. EADDRINUSE + } + console.log(`Listening on ${JSON.stringify(server.address())}`); +}); +``` + +### app.router + +Express 4 で削除された `app.router` オブジェクトは、Express 5 で復活しました。 新しいバージョンでは、このオブジェクトはベース Express ルータへの単なる参照です。 アプリが明示的にロードしなければならなかったExpress 3とは異なります。 + +### req.body + +`req.body` プロパティは、本文が解析されていない場合に `undefined` を返します。 Express 4 ではデフォルトで `{}` を返します。 + +### req.host + +Express 4では、`req.host`関数がポート番号を間違って剥奪しました。 Express 5ではポート番号が維持されています。 + +### req.params + +`req.params` オブジェクトに文字列パスを使用する際に **null プロトタイプ** が追加されました。 しかし、パスが正規表現で定義されている場合、`req.params` は通常のプロトタイプを持つ標準オブジェクトのままです。 さらに、2つの重要な行動変更があります。 + +**ワイルドカードパラメータは配列になりました:** + +ワイルドカード(例: `/*splat`)は単一の文字列の代わりにパスセグメントを配列として取り込みます。 + +```js +app.get('/*splat', (req, res) => { + // GET /foo/bar + console.dir(req.params); + // => [Object: null prototype] { splat: [ 'foo', 'bar' ] } +}); +``` + +**マッチしないパラメータは省略されました:** + +Express 4では、マッチしないワイルドカードは空文字列(`'`)であり、オプションのパラメータ(`?`を使用)には値が`undefined`のキーがありました。 Express 5 では、マッチしないパラメータは `req.params` から完全に省略されます。 + +```js +// v4: unmatched wildcard is empty string +app.get('/*', (req, res) => { + // GET / + console.dir(req.params); + // => { '0': '' } +}); + +// v4: unmatched optional param is undefined +app.get('/:file.:ext?', (req, res) => { + // GET /image + console.dir(req.params); + // => { file: 'image', ext: undefined } +}); + +// v5: unmatched optional param is omitted +app.get('/:file{.:ext}', (req, res) => { + // GET /image + console.dir(req.params); + // => [Object: null prototype] { file: 'image' } +}); +``` + +### req.query + +`req.query` プロパティはもはや書き込み可能なプロパティではなく、代わりにゲッターです。 デフォルトのクエリパーサが"extended"から"simple"に変更されました。 + +### res.clearCookie + +`res.clearCookie`メソッドは、ユーザーが提供する`maxAge`と`expires`オプションを無視します。 + +### res.status + +`res.status` メソッドは、Node によって定義された動作に従い、`100` から `999` の範囲の整数のみを受け付けます。 s, そしてステータスコードが整数でない場合にエラーを返します。 + +### res.variable + +`field`引数がない場合、`res.vary`はエラーをスローします。 Express 4では、引数が省略された場合、コンソールに警告が表示されました。 + +## 改善 + +### res.render() + +このメソッドは、すべてのビューエンジンの非同期動作を強制するようになりました。 同期実装されたビューエンジンによるバグを回避し、推奨されるインターフェイスに違反していました。 + +### Brotliエンコーディングのサポート + +Express 5では、サポートしているクライアントから受信したリクエストに対応するBrotliエンコーディングに対応しています。 diff --git a/src/content/pages/ja/resources/glossary.mdx b/src/content/pages/ja/resources/glossary.mdx new file mode 100644 index 0000000000..c630340325 --- /dev/null +++ b/src/content/pages/ja/resources/glossary.mdx @@ -0,0 +1,61 @@ +--- +title: Glossary +description: Express.js、Node.js、ミドルウェア、ルーティング、その他の重要な概念に関連する包括的な用語集で、Expressを効果的に理解し使用するのに役立ちます。 +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +### アプリケーション + +一般に、特定の目的のために操作を実行するように設計された1つまたは複数のプログラム。 Express のコンテキストでは、Node.js プラットフォームで実行される Express API を使用するプログラムがあります。 [app object](/en/api#express) も参照しているかもしれません。 + +### API + +アプリケーションプログラミングインターフェイス。 略語が最初に使用されたときにスペルアウトします。 + +### エクスプレス + +Node.jsアプリケーション用の高速で、意見が異なる、ミニマリストなWebフレームワーク。 一般的には「Express」は「Express.js」よりも好まれますが、後者は許容されます。 + +### libuv + +非同期I/Oに焦点を当てたマルチプラットフォームサポートライブラリ。主にNode.jsで使用するために開発されました。 + +### middleware + +最後のリクエストハンドラの前に Express ルーティング層によって呼び出される関数 生の要求と最終目的のルートの間に座っています ミドルウェアに関する用語のいくつかの細かい点: + +* `var foo = require('middleware')` は Node.js モジュールの *requiring* または *using* と呼ばれます。 `var mw = foo()`という文は通常、ミドルウェアを返します。 +* `app.use(mw)`は、ミドルウェアをグローバルな処理スタックに追加することを呼びます。 +* `app.get('/foo', mw, function (req, res) { ... })` は、ミドルウェアを "GET /foo" 処理の stack_ に追加すると呼ばれます。 + +### Node.js + +スケーラブルなネットワークアプリケーションの構築に使用されるソフトウェアプラットフォーム。 Node.jsはJavaScriptをスクリプト言語として使用し、ノンブロッキングI/Oとシングルスレッドイベントループにより高いスループットを実現します。 [nodejs.org](https://nodejs.org/en/) を参照してください。 **使用上の注意**: 最初は、"Node.js"以降は"Node"です。 + +### オープンソースのオープンソース + +形容詞として使われる場合、ハイフネートなど。例: "これはオープンソースソフトウェアです。 [Wikipediaのオープンソースソフトウェア](http://en.wikipedia.org/wiki/Open-source_software)を参照してください。 + + + +この用語をハイフネーションしないことは一般的ですが、 +の標準的な英語規則を用いて複合形容詞をハイフネーションします。 + + + +### リクエスト + +HTTP リクエスト。 クライアントは、レスポンスを返すサーバーに HTTP リクエストメッセージを送信します。 リクエストは、GET、POST など、いくつかの [request methods](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) のうちの 1 つを使用する必要があります。 + +### 応答 + +HTTPレスポンス。 サーバーはクライアントに HTTP 応答メッセージを返します。 レスポンスには、リクエストに関する完了ステータス情報が含まれており、メッセージ本文に要求されたコンテンツが含まれている場合もあります。 + +### route + +リソースを識別する URL の一部です。 例えば、`http://foo.com/products/id`では、"/products/id"がルートです。 + +### ルーター: + +API リファレンスの [router](/en/api#router) を参照してください。 diff --git a/src/content/pages/ja/resources/utils.md b/src/content/pages/ja/resources/utils.md new file mode 100644 index 0000000000..f3268163d1 --- /dev/null +++ b/src/content/pages/ja/resources/utils.md @@ -0,0 +1,22 @@ +--- +title: エクスプレスユーティリティ +description: Express.jsとNode.jsに関連するユーティリティモジュール、Cookie、CSRF保護、URLの解析、ルーティングなど、アプリケーションを強化するためのツールを含む。 +--- + +## Express ユーティリティ関数 + +[pillarjs](https://github.com/pillarjs) GitHub Organization には、一般的に便利なユーティリティ関数用の多くのモジュール +が含まれています。 + +| ユーティリティモジュール | 説明 | +| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | +| [cookies](https://www.npmjs.com/package/cookies) | HTTP(S) Cookie を取得して設定し、改ざんを防ぐために署名できます。Keygrip を使用します。 Node.js HTTP ライブラリまたは Express ミドルウェアとして使用できます。 | +| [csrf](https://www.npmjs.com/package/csrf) | CSRFトークンの作成と検証の背後にあるロジックが含まれています。 このモジュールを使用して、カスタム CSRF ミドルウェアを作成します。 | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | HTTP リクエストに応答するための最後のステップとして呼び出す関数。 | +| [parseurl](https://www.npmjs.com/package/parseurl) | URLをキャッシュで解析します。 | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | \`\`/user/:name\`のようなExpressスタイルのパス文字列を正規表現に変換します。 | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | 検証されたルートパスに対して相対パスを解決します。 | +| [router](https://www.npmjs.com/package/router) | シンプルなミドルウェアスタイルのルータ。 | +| [send](https://www.npmjs.com/package/send) | HTTP レスポンスとしてファイルをストリーミングするためのライブラリで、部分的な応答 (範囲)、条件付きの GET ネゴシエーション、および細かいイベントをサポートします。 | + +低レベルの HTTP 関連モジュールについては、 [jshttp](https://github.com/jshttp) を参照してください。 diff --git a/src/content/pages/ja/support.md b/src/content/pages/ja/support.md new file mode 100644 index 0000000000..f1b922c32e --- /dev/null +++ b/src/content/pages/ja/support.md @@ -0,0 +1,23 @@ +--- +title: バージョンサポート +description: 現在メンテナンスされているバージョンや終了ポリシーを含む、さまざまなExpress.jsバージョンのサポートスケジュールに関する情報をご覧ください。 +--- + +任意のメジャーリリースラインの最新バージョンのみがサポートされています。 + +EOL (終了) _may_ のバージョンは、重大なセキュリティ脆弱性の更新を受け取ります。 しかし、Expressチームは保証を提供しておらず、見つかった問題の修正やリリースを計画していません。 + +| メジャーバージョン | 最小Node.js バージョン | サポート開始日 | サポート終了日 | +| ------------------------------------------- | -------------------------------------- | ---------- | ---------- | +| [**v5.x**](/en/5x/api) | 18 | 2024年9月 | **進行中** | +| [**v4.x**](/en/4x/api) | 0.10.0 | 2014 年 4 月 | **進行中** | +| [**v3.x**](/en/3x/api) | 0.8.0 | 2012年10月 | 2015 年 7 月 | +| [**v2.x**](/2x/) | 0.4.1 | 2011 年 3 月 | 2012 年 7 月 | +| **v1.x** | 0.2.0 | 2010年12月 | 2011 年 3 月 | +| **v0.14.x** | 0.1.98 | 2010年12月 | 2010年12月 | + +## 商用サポートオプション + +サポートされているバージョンの Express にアップデートできない場合は、以下のいずれかのパートナーにお問い合わせください: + +- [HeroDevs Never-Ending Support](http://www.herodevs.com/support/express-nes?utm_source=expressjs&utm_medium=link&utm_campaign=express_eol_page) diff --git a/src/content/pages/ko/advanced/best-practice-performance.md b/src/content/pages/ko/advanced/best-practice-performance.md new file mode 100644 index 0000000000..a98c7fcf6a --- /dev/null +++ b/src/content/pages/ko/advanced/best-practice-performance.md @@ -0,0 +1,305 @@ +--- +title: 'Production best practices: performance and reliability' +description: Discover performance and reliability best practices for Express apps in production, covering code optimizations and environment setups for optimal performance. +--- + +This article discusses performance and reliability best practices for Express applications deployed to production. + +This topic clearly falls into the "devops" world, spanning both traditional development and operations. Accordingly, the information is divided into two parts: + +- Things to do in your code (the dev part): + - [Use gzip compression](#use-gzip-compression) + - [Don't use synchronous functions](#dont-use-synchronous-functions) + - [Do logging correctly](#do-logging-correctly) + - [Handle exceptions properly](#handle-exceptions-properly) +- Things to do in your environment / setup (the ops part): + - [Set NODE_ENV to "production"](#set-node_env-to-production) + - [Ensure your app automatically restarts](#ensure-your-app-automatically-restarts) + - [Run your app in a cluster](#run-your-app-in-a-cluster) + - [Cache request results](#cache-request-results) + - [Use a load balancer](#use-a-load-balancer) + - [Use a reverse proxy](#use-a-reverse-proxy) + +## Things to do in your code + +Here are some things you can do in your code to improve your application's performance: + +- [Use gzip compression](#use-gzip-compression) +- [Don't use synchronous functions](#dont-use-synchronous-functions) +- [Do logging correctly](#do-logging-correctly) +- [Handle exceptions properly](#handle-exceptions-properly) + +### Use gzip compression + +Gzip compressing can greatly decrease the size of the response body and hence increase the speed of a web app. Use the [compression](https://www.npmjs.com/package/compression) middleware for gzip compression in your Express app. For example: + +```js +const compression = require('compression'); +const express = require('express'); +const app = express(); + +app.use(compression()); +``` + +For a high-traffic website in production, the best way to put compression in place is to implement it at a reverse proxy level (see [Use a reverse proxy](#use-a-reverse-proxy)). In that case, you do not need to use compression middleware. For details on enabling gzip compression in Nginx, see [Module ngx_http_gzip_module](http://nginx.org/en/docs/http/ngx_http_gzip_module) in the Nginx documentation. + +### Don't use synchronous functions + +Synchronous functions and methods tie up the executing process until they return. A single call to a synchronous function might return in a few microseconds or milliseconds, however in high-traffic websites, these calls add up and reduce the performance of the app. Avoid their use in production. + +Although Node and many modules provide synchronous and asynchronous versions of their functions, always use the asynchronous version in production. The only time when a synchronous function can be justified is upon initial startup. + +You can use the `--trace-sync-io` command-line flag to print a warning and a stack trace whenever your application uses a synchronous API. Of course, you wouldn't want to use this in production, but rather to ensure that your code is ready for production. See the [node command-line options documentation](https://nodejs.org/api/cli#cli_trace_sync_io) for more information. + +### Do logging correctly + +In general, there are two reasons for logging from your app: For debugging and for logging app activity (essentially, everything else). Using `console.log()` or `console.error()` to print log messages to the terminal is common practice in development. But [these functions are synchronous](https://nodejs.org/api/console#console) when the destination is a terminal or a file, so they are not suitable for production, unless you pipe the output to another program. + +#### For debugging + +If you're logging for purposes of debugging, then instead of using `console.log()`, use a special debugging module like [debug](https://www.npmjs.com/package/debug). This module enables you to use the DEBUG environment variable to control what debug messages are sent to `console.error()`, if any. To keep your app purely asynchronous, you'd still want to pipe `console.error()` to another program. But then, you're not really going to debug in production, are you? + +#### For app activity + +If you're logging app activity (for example, tracking traffic or API calls), instead of using `console.log()`, use a logging library like [Pino](https://www.npmjs.com/package/pino), which is the fastest and most efficient option available. + +### Handle exceptions properly + +Node apps crash when they encounter an uncaught exception. Not handling exceptions and taking appropriate actions will make your Express app crash and go offline. If you follow the advice in [Ensure your app automatically restarts](#ensure-your-app-automatically-restarts) below, then your app will recover from a crash. Fortunately, Express apps typically have a short startup time. Nevertheless, you want to avoid crashing in the first place, and to do that, you need to handle exceptions properly. + +To ensure you handle all exceptions, use the following techniques: + +- [Use try-catch](#use-try-catch) +- [Use promises](#use-promises) + +Before diving into these topics, you should have a basic understanding of Node/Express error handling: using error-first callbacks, and propagating errors in middleware. Node uses an "error-first callback" convention for returning errors from asynchronous functions, where the first parameter to the callback function is the error object, followed by result data in succeeding parameters. To indicate no error, pass null as the first parameter. The callback function must correspondingly follow the error-first callback convention to meaningfully handle the error. And in Express, the best practice is to use the next() function to propagate errors through the middleware chain. + +For more on the fundamentals of error handling, see: + +- [Error Handling in Node.js](https://www.tritondatacenter.com/node-js/production/design/errors) + +#### Use try-catch + +Try-catch is a JavaScript language construct that you can use to catch exceptions in synchronous code. Use try-catch, for example, to handle JSON parsing errors as shown below. + +Here is an example of using try-catch to handle a potential process-crashing exception. +This middleware function accepts a query field parameter named "params" that is a JSON object. + +```js +app.get('/search', (req, res) => { + // Simulating async operation + setImmediate(() => { + const jsonStr = req.query.params; + try { + const jsonObj = JSON.parse(jsonStr); + res.send('Success'); + } catch (e) { + res.status(400).send('Invalid JSON string'); + } + }); +}); +``` + +However, try-catch works only for synchronous code. Because the Node platform is primarily asynchronous (particularly in a production environment), try-catch won't catch a lot of exceptions. + +#### Use promises + +When an error is thrown in an `async` function or a rejected promise is awaited inside an `async` function, those errors will be passed to the error handler as if calling `next(err)` + +```js +app.get('/', async (req, res, next) => { + const data = await userData(); // If this promise fails, it will automatically call `next(err)` to handle the error. + + res.send(data); +}); + +app.use((err, req, res, next) => { + res.status(err.status ?? 500).send({ error: err.message }); +}); +``` + +Also, you can use asynchronous functions for your middleware, and the router will handle errors if the promise fails, for example: + +```js +app.use(async (req, res, next) => { + req.locals.user = await getUser(req); + + next(); // This will be called if the promise does not throw an error. +}); +``` + +Best practice is to handle errors as close to the site as possible. So while this is now handled in the router, it’s best to catch the error in the middleware and handle it without relying on separate error-handling middleware. + +#### What not to do + +One thing you should _not_ do is to listen for the `uncaughtException` event, emitted when an exception bubbles all the way back to the event loop. Adding an event listener for `uncaughtException` will change the default behavior of the process that is encountering an exception; the process will continue to run despite the exception. This might sound like a good way of preventing your app from crashing, but continuing to run the app after an uncaught exception is a dangerous practice and is not recommended, because the state of the process becomes unreliable and unpredictable. + +Additionally, using `uncaughtException` is officially recognized as [crude](https://nodejs.org/api/process#process_event_uncaughtexception). So listening for `uncaughtException` is just a bad idea. This is why we recommend things like multiple processes and supervisors: crashing and restarting is often the most reliable way to recover from an error. + +We also don't recommend using [domains](https://nodejs.org/api/domain). It generally doesn't solve the problem and is a deprecated module. + +## Things to do in your environment / setup + +Here are some things you can do in your system environment to improve your app's performance: + +- [Set NODE_ENV to "production"](#set-node_env-to-production) +- [Ensure your app automatically restarts](#ensure-your-app-automatically-restarts) +- [Run your app in a cluster](#run-your-app-in-a-cluster) +- [Cache request results](#cache-request-results) +- [Use a load balancer](#use-a-load-balancer) +- [Use a reverse proxy](#use-a-reverse-proxy) + +### Set NODE_ENV to "production" + +The NODE_ENV environment variable specifies the environment in which an application is running (usually, development or production). One of the simplest things you can do to improve performance is to set NODE_ENV to `production`. + +Setting NODE_ENV to "production" makes Express: + +- Cache view templates. +- Cache CSS files generated from CSS extensions. +- Generate less verbose error messages. + +[Tests indicate](https://www.dynatrace.com/news/blog/the-drastic-effects-of-omitting-node-env-in-your-express-js-applications/) that just doing this can improve app performance by a factor of three! + +If you need to write environment-specific code, you can check the value of NODE_ENV with `process.env.NODE_ENV`. Be aware that checking the value of any environment variable incurs a performance penalty, and so should be done sparingly. + +In development, you typically set environment variables in your interactive shell, for example by using `export` or your `.bash_profile` file. But in general, you shouldn't do that on a production server; instead, use your OS's init system (systemd). The next section provides more details about using your init system in general, but setting `NODE_ENV` is so important for performance (and easy to do), that it's highlighted here. + +With systemd, use the `Environment` directive in your unit file. For example: + +```sh + +Environment=NODE_ENV=production +``` + +For more information, see [Using Environment Variables In systemd Units](https://www.flatcar.org/docs/latest/setup/systemd/environment-variables/). + +### Ensure your app automatically restarts + +In production, you don't want your application to be offline, ever. This means you need to make sure it restarts both if the app crashes and if the server itself crashes. Although you hope that neither of those events occurs, realistically you must account for both eventualities by: + +- Using a process manager to restart the app (and Node) when it crashes. +- Using the init system provided by your OS to restart the process manager when the OS crashes. It's also possible to use the init system without a process manager. + +Node applications crash if they encounter an uncaught exception. The foremost thing you need to do is to ensure your app is well-tested and handles all exceptions (see [handle exceptions properly](#handle-exceptions-properly) for details). But as a fail-safe, put a mechanism in place to ensure that if and when your app crashes, it will automatically restart. + +#### Use a process manager + +In development, you started your app simply from the command line with `node server.js` or something similar. But doing this in production is a recipe for disaster. If the app crashes, it will be offline until you restart it. To ensure your app restarts if it crashes, use a process manager. A process manager is a "container" for applications that facilitates deployment, provides high availability, and enables you to manage the application at runtime. + +In addition to restarting your app when it crashes, a process manager can enable you to: + +- Gain insights into runtime performance and resource consumption. +- Modify settings dynamically to improve performance. +- Control clustering (pm2). + +Historically, it was popular to use a Node.js process manager like [PM2](https://github.com/Unitech/pm2). See their documentation if you wish to do this. However, we recommend using your init system for process management. + +#### Use an init system + +The next layer of reliability is to ensure that your app restarts when the server restarts. Systems can still go down for a variety of reasons. To ensure that your app restarts if the server crashes, use the init system built into your OS. The main init system in use today is [systemd](https://wiki.debian.org/systemd). + +There are two ways to use init systems with your Express app: + +- Run your app in a process manager, and install the process manager as a service with the init system. The process manager will restart your app when the app crashes, and the init system will restart the process manager when the OS restarts. This is the recommended approach. +- Run your app (and Node) directly with the init system. This is somewhat simpler, but you don't get the additional advantages of using a process manager. + +##### Systemd + +Systemd is a Linux system and service manager. Most major Linux distributions have adopted systemd as their default init system. + +A systemd service configuration file is called a _unit file_, with a filename ending in `.service`. Here's an example unit file to manage a Node app directly. Replace the values enclosed in `` for your system and app: + +```sh +[Unit] +Description= + +[Service] +Type=simple +ExecStart=/usr/local/bin/node +WorkingDirectory= + +User=nobody +Group=nogroup + + +Environment=NODE_ENV=production + + +LimitNOFILE=infinity + + +LimitCORE=infinity + +StandardInput=null +StandardOutput=syslog +StandardError=syslog +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +For more information on systemd, see the [systemd reference (man page)](http://www.freedesktop.org/software/systemd/man/systemd.unit). + +### Run your app in a cluster + +In a multi-core system, you can increase the performance of a Node app by many times by launching a cluster of processes. A cluster runs multiple instances of the app, ideally one instance on each CPU core, thereby distributing the load and tasks among the instances. + +![Balancing between application instances using the cluster API](/images/clustering.png) + +IMPORTANT: Since the app instances run as separate processes, they do not share the same memory space. That is, objects are local to each instance of the app. Therefore, you cannot maintain state in the application code. However, you can use an in-memory datastore like [Redis](http://redis.io/) to store session-related data and state. This caveat applies to essentially all forms of horizontal scaling, whether clustering with multiple processes or multiple physical servers. + +In clustered apps, worker processes can crash individually without affecting the rest of the processes. Apart from performance advantages, failure isolation is another reason to run a cluster of app processes. Whenever a worker process crashes, always make sure to log the event and spawn a new process using cluster.fork(). + +#### Using Node's cluster module + +Clustering is made possible with Node's [cluster module](https://nodejs.org/api/cluster). This enables a master process to spawn worker processes and distribute incoming connections among the workers. + +#### Using PM2 + +If you deploy your application with PM2, then you can take advantage of clustering _without_ modifying your application code. You should ensure your [application is stateless](https://pm2.keymetrics.io/docs/usage/specifics/#stateless-apps) first, meaning no local data is stored in the process (such as sessions, websocket connections and the like). + +When running an application with PM2, you can enable **cluster mode** to run it in a cluster with a number of instances of your choosing, such as the matching the number of available CPUs on the machine. You can manually change the number of processes in the cluster using the `pm2` command line tool without stopping the app. + +To enable cluster mode, start your application like so: + +```bash + +$ pm2 start npm --name my-app -i 4 -- start + +$ pm2 start npm --name my-app -i max -- start +``` + +This can also be configured within a PM2 process file (`ecosystem.config.js` or similar) by setting `exec_mode` to `cluster` and `instances` to the number of workers to start. + +Once running, the application can be scaled like so: + +```bash + +$ pm2 scale my-app +3 + +$ pm2 scale my-app 2 +``` + +For more information on clustering with PM2, see [Cluster Mode](https://pm2.keymetrics.io/docs/usage/cluster-mode/) in the PM2 documentation. + +### Cache request results + +Another strategy to improve the performance in production is to cache the result of requests, so that your app does not repeat the operation to serve the same request repeatedly. + +Use a caching server like [Varnish](https://www.varnish-cache.org/) or [Nginx](https://blog.nginx.org/blog/nginx-caching-guide) (see also [Nginx Caching](https://serversforhackers.com/nginx-caching/)) to greatly improve the speed and performance of your app. + +### Use a load balancer + +No matter how optimized an app is, a single instance can handle only a limited amount of load and traffic. One way to scale an app is to run multiple instances of it and distribute the traffic via a load balancer. Setting up a load balancer can improve your app's performance and speed, and enable it to scale more than is possible with a single instance. + +A load balancer is usually a reverse proxy that orchestrates traffic to and from multiple application instances and servers. You can easily set up a load balancer for your app by using [Nginx](https://nginx.org/en/docs/http/load_balancing) or [HAProxy](https://www.digitalocean.com/community/tutorials/an-introduction-to-haproxy-and-load-balancing-concepts). + +With load balancing, you might have to ensure that requests that are associated with a particular session ID connect to the process that originated them. This is known as _session affinity_, or _sticky sessions_, and may be addressed by the suggestion above to use a data store such as Redis for session data (depending on your application). For a discussion, see [Using multiple nodes](https://socket.io/docs/v4/using-multiple-nodes/). + +### Use a reverse proxy + +A reverse proxy sits in front of a web app and performs supporting operations on the requests, apart from directing requests to the app. It can handle error pages, compression, caching, serving files, and load balancing among other things. + +Handing over tasks that do not require knowledge of application state to a reverse proxy frees up Express to perform specialized application tasks. For this reason, it is recommended to run Express behind a reverse proxy like [Nginx](https://www.nginx.org/) or [HAProxy](https://www.haproxy.org/) in production. diff --git a/src/content/pages/ko/advanced/best-practice-security.mdx b/src/content/pages/ko/advanced/best-practice-security.mdx new file mode 100644 index 0000000000..fa7b7622bb --- /dev/null +++ b/src/content/pages/ko/advanced/best-practice-security.mdx @@ -0,0 +1,276 @@ +--- +title: "Production Best Practices: Security" +description: Discover crucial security best practices for Express apps in production, including using TLS, input validation, secure cookies, and preventing vulnerabilities. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +The term *"production"* refers to the stage in the software lifecycle when an application or API is generally available to its end-users or consumers. In contrast, in the *"development"* stage, you're still actively writing and testing code, and the application is not open to external access. The corresponding system environments are known as *production* and *development* environments, respectively. + +Development and production environments are usually set up differently and have vastly different requirements. What's fine in development may not be acceptable in production. For example, in a development environment you may want verbose logging of errors for debugging, while the same behavior can become a security concern in a production environment. And in development, you don't need to worry about scalability, reliability, and performance, while those concerns become critical in production. + + + +If you believe you have discovered a security vulnerability in Express, please see Security +Policies and Procedures. + + + +Security best practices for Express applications in production include: + +* [Production Best Practices: Security](#production-best-practices-security) + * [Overview](#overview) + * [Don't use deprecated or vulnerable versions of Express](#dont-use-deprecated-or-vulnerable-versions-of-express) + * [Use TLS](#use-tls) + * [Do not trust user input](#do-not-trust-user-input) + * [Prevent open redirects](#prevent-open-redirects) + * [Use Helmet](#use-helmet) + * [Reduce fingerprinting](#reduce-fingerprinting) + * [Use cookies securely](#use-cookies-securely) + * [Don't use the default session cookie name](#dont-use-the-default-session-cookie-name) + * [Set cookie security options](#set-cookie-security-options) + * [Prevent brute-force attacks against authorization](#prevent-brute-force-attacks-against-authorization) + * [Ensure your dependencies are secure](#ensure-your-dependencies-are-secure) + * [Avoid other known vulnerabilities](#avoid-other-known-vulnerabilities) + * [Additional considerations](#additional-considerations) + +## Don't use deprecated or vulnerable versions of Express + +Express 2.x and 3.x are no longer maintained. Security and performance issues in these versions won't be fixed. Do not use them! If you haven't moved to version 4, follow the [migration guide](/en/guide/migrating-4) or consider [Commercial Support Options](/en/support#commercial-support-options). + +Also ensure you are not using any of the vulnerable Express versions listed on the [Security updates page](/en/advanced/security-updates). If you are, update to one of the stable releases, preferably the latest. + +## Use TLS + +If your app deals with or transmits sensitive data, use [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) to secure the connection and the data. This technology encrypts data before it is sent from the client to the server, thus preventing some common (and easy) hacks. Although Ajax and POST requests might not be visibly obvious and seem "hidden" in browsers, their network traffic is vulnerable to [packet sniffing](https://en.wikipedia.org/wiki/Packet_analyzer) and [man-in-the-middle attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). + +You may be familiar with Secure Socket Layer (SSL) encryption. [TLS is simply the next progression of SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). In other words, if you were using SSL before, consider upgrading to TLS. In general, we recommend Nginx to handle TLS. For a good reference to configure TLS on Nginx (and other servers), see [Recommended Server Configurations (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). + +Also, a handy tool to get a free TLS certificate is [Let's Encrypt](https://letsencrypt.org/about/), a free, automated, and open certificate authority (CA) provided by the [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). + +## Do not trust user input + +For web applications, one of the most critical security requirements is proper user input validation and handling. This comes in many forms and we will not cover all of them here. +Ultimately, the responsibility for validating and correctly handling the types of user input your application accepts is yours. + +### Prevent open redirects + +An example of potentially dangerous user input is an *open redirect*, where an application accepts a URL as user input (often in the URL query, for example `?url=https://example.com`) and uses `res.redirect` to set the `location` header and +return a 3xx status. + +An application must validate that it supports redirecting to the incoming URL to avoid sending users to malicious links such as phishing websites, among other risks. + +Here is an example of checking URLs before using `res.redirect` or `res.location`: + +```js +app.use((req, res) => { + try { + if (new Url(req.query.url).host !== 'example.com') { + return res.status(400).end(`Unsupported redirect to host: ${req.query.url}`); + } + } catch (e) { + return res.status(400).end(`Invalid url: ${req.query.url}`); + } + res.redirect(req.query.url); +}); +``` + +## Use Helmet + +[Helmet][helmet] can help protect your app from some well-known web vulnerabilities by setting HTTP headers appropriately. + +Helmet is a middleware function that sets security-related HTTP response headers. Helmet sets the following headers by default: + +* `Content-Security-Policy`: A powerful allow-list of what can happen on your page which mitigates many attacks +* `Cross-Origin-Opener-Policy`: Helps process-isolate your page +* `Cross-Origin-Resource-Policy`: Blocks others from loading your resources cross-origin +* `Origin-Agent-Cluster`: Changes process isolation to be origin-based +* `Referrer-Policy`: Controls the [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) header +* `Strict-Transport-Security`: Tells browsers to prefer HTTPS +* `X-Content-Type-Options`: Avoids [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +* `X-DNS-Prefetch-Control`: Controls DNS prefetching +* `X-Download-Options`: Forces downloads to be saved (Internet Explorer only) +* `X-Frame-Options`: Legacy header that mitigates [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) attacks +* `X-Permitted-Cross-Domain-Policies`: Controls cross-domain behavior for Adobe products, like Acrobat +* `X-Powered-By`: Info about the web server. Removed because it could be used in simple attacks +* `X-XSS-Protection`: Legacy header that tries to mitigate [XSS attacks](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), but makes things worse, so Helmet disables it + +Each header can be configured or disabled. To read more about it please go to [its documentation website][helmet]. + +Install Helmet like any other module: + +```bash +$ npm install helmet +``` + +Then to use it in your code: + +```js +// ... + +const helmet = require('helmet'); +app.use(helmet()); + +// ... +``` + +## Reduce fingerprinting + +It can help to provide an extra layer of security to reduce the ability of attackers to determine +the software that a server uses, known as "fingerprinting." Though not a security issue itself, +reducing the ability to fingerprint an application improves its overall security posture. +Server software can be fingerprinted by quirks in how it responds to specific requests, for example in +the HTTP response headers. + +By default, Express sends the `X-Powered-By` response header that you can +disable using the `app.disable()` method: + +```js +app.disable('x-powered-by'); +``` + + + +Disabling the `X-Powered-By header` does not prevent a sophisticated attacker from determining +that an app is running Express. It may discourage a casual exploit, but there are other ways to +determine an app is running Express. + + + +Express also sends its own formatted "404 Not Found" messages and formatter error +response messages. These can be changed by +[adding your own not found handler](/en/starter/faq#how-do-i-handle-404-responses) +and +[writing your own error handler](/en/guide/error-handling#writing-error-handlers): + +```js +// last app.use calls right before app.listen(): + +// custom 404 +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); + +// custom error handler +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +## Use cookies securely + +To ensure cookies don't open your app to exploits, don't use the default session cookie name and set cookie security options appropriately. + +There are two main middleware cookie session modules: + +* [express-session](https://www.npmjs.com/package/express-session) that replaces `express.session` middleware built-in to Express 3.x. +* [cookie-session](https://www.npmjs.com/package/cookie-session) that replaces `express.cookieSession` middleware built-in to Express 3.x. + +The main difference between these two modules is how they save cookie session data. The [express-session](https://www.npmjs.com/package/express-session) middleware stores session data on the server; it only saves the session ID in the cookie itself, not session data. By default, it uses in-memory storage and is not designed for a production environment. In production, you'll need to set up a scalable session-store; see the list of [compatible session stores](https://github.com/expressjs/session#compatible-session-stores). + +In contrast, [cookie-session](https://www.npmjs.com/package/cookie-session) middleware implements cookie-backed storage: it serializes the entire session to the cookie, rather than just a session key. Only use it when session data is relatively small and easily encoded as primitive values (rather than objects). Although browsers are supposed to support at least 4096 bytes per cookie, to ensure you don't exceed the limit, don't exceed a size of 4093 bytes per domain. Also, be aware that the cookie data will be visible to the client, so if there is any reason to keep it secure or obscure, then `express-session` may be a better choice. + +### Don't use the default session cookie name + +Using the default session cookie name can open your app to attacks. The security issue posed is similar to `X-Powered-By`: a potential attacker can use it to fingerprint the server and target attacks accordingly. + +To avoid this problem, use generic cookie names; for example using [express-session](https://www.npmjs.com/package/express-session) middleware: + +```js +const session = require('express-session'); +app.set('trust proxy', 1); // trust first proxy +app.use( + session({ + secret: 's3Cur3', + name: 'sessionId', + }) +); +``` + +### Set cookie security options + +Set the following cookie options to enhance security: + +* `secure` - Ensures the browser only sends the cookie over HTTPS. +* `httpOnly` - Ensures the cookie is sent only over HTTP(S), not client JavaScript, helping to protect against cross-site scripting attacks. +* `domain` - indicates the domain of the cookie; use it to compare against the domain of the server in which the URL is being requested. If they match, then check the path attribute next. +* `path` - indicates the path of the cookie; use it to compare against the request path. If this and domain match, then send the cookie in the request. +* `expires` - use to set expiration date for persistent cookies. + +Here is an example using [cookie-session](https://www.npmjs.com/package/cookie-session) middleware: + +```js +const session = require('cookie-session'); +const express = require('express'); +const app = express(); + +const expiryDate = new Date(Date.now() + 60 * 60 * 1000); // 1 hour +app.use( + session({ + name: 'session', + keys: ['key1', 'key2'], + cookie: { + secure: true, + httpOnly: true, + domain: 'example.com', + path: 'foo/bar', + expires: expiryDate, + }, + }) +); +``` + +## Prevent brute-force attacks against authorization + +Make sure login endpoints are protected to make private data more secure. + +A simple and powerful technique is to block authorization attempts using two metrics: + +1. The number of consecutive failed attempts by the same user name and IP address. +2. The number of failed attempts from an IP address over some long period of time. For example, block an IP address if it makes 100 failed attempts in one day. + +[rate-limiter-flexible](https://github.com/animir/node-rate-limiter-flexible) package provides tools to make this technique easy and fast. You can find [an example of brute-force protection in the documentation](https://github.com/animir/node-rate-limiter-flexible/wiki/Overall-example#login-endpoint-protection) + +## Ensure your dependencies are secure + +Using npm to manage your application's dependencies is powerful and convenient. But the packages that you use may contain critical security vulnerabilities that could also affect your application. The security of your app is only as strong as the "weakest link" in your dependencies. + +Since npm@6, npm automatically reviews every install request. Also, you can use `npm audit` to analyze your dependency tree. + +```bash +$ npm audit +``` + +If you want to stay more secure, consider [Snyk](https://snyk.io/). + +Snyk offers both a [command-line tool](https://www.npmjs.com/package/snyk) and a [Github integration](https://snyk.io/docs/github) that checks your application against [Snyk's open source vulnerability database](https://snyk.io/vuln/) for any known vulnerabilities in your dependencies. Install the CLI as follows: + +```bash +$ npm install -g snyk +$ cd your-app +``` + +Use this command to test your application for vulnerabilities: + +```bash +$ snyk test +``` + +### Avoid other known vulnerabilities + +Keep an eye out for [Node Security Project](https://npmjs.com/advisories) or [Snyk](https://snyk.io/vuln/) advisories that may affect Express or other modules that your app uses. In general, these databases are excellent resources for knowledge and tools about Node security. + +Finally, Express apps—like any other web apps—can be vulnerable to a variety of web-based attacks. Familiarize yourself with known [web vulnerabilities](https://www.owasp.org/www-project-top-ten/) and take precautions to avoid them. + +## Additional considerations + +Here are some further recommendations from the excellent [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/). Refer to that blog post for all the details on these recommendations: + +* Always filter and sanitize user input to protect against cross-site scripting (XSS) and command injection attacks. +* Defend against SQL injection attacks by using parameterized queries or prepared statements. +* Use the open-source [sqlmap](http://sqlmap.org/) tool to detect SQL injection vulnerabilities in your app. +* Use the [nmap](https://nmap.org/) and [sslyze](https://github.com/nabla-c0d3/sslyze) tools to test the configuration of your SSL ciphers, keys, and renegotiation as well as the validity of your certificate. +* Use [safe-regex](https://www.npmjs.com/package/safe-regex) to ensure your regular expressions are not susceptible to [regular expression denial of service](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) attacks. + +[helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/ko/advanced/healthcheck-graceful-shutdown.md b/src/content/pages/ko/advanced/healthcheck-graceful-shutdown.md new file mode 100644 index 0000000000..c060e58605 --- /dev/null +++ b/src/content/pages/ko/advanced/healthcheck-graceful-shutdown.md @@ -0,0 +1,28 @@ +--- +title: Health Checks and Graceful Shutdown +description: Learn how to implement health checks and graceful shutdown in Express apps to enhance reliability, manage deployments, and integrate with load balancers like Kubernetes. +--- + +## Graceful shutdown + +When you deploy a new version of your application, you must replace the previous version. The process manager you're using will first send a SIGTERM signal to the application to notify it that it will be killed. Once the application gets this signal, it should stop accepting new requests, finish all the ongoing requests, clean up the resources it used, including database connections and file locks then exit. + +### Example + +```js +const server = app.listen(port); + +process.on('SIGTERM', () => { + debug('SIGTERM signal received: closing HTTP server'); + server.close(() => { + debug('HTTP server closed'); + }); +}); +``` + +## Health checks + +A load balancer uses health checks to determine if an application instance is healthy and can accept requests. For example, [Kubernetes has two health checks](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/): + +- `liveness`, that determines when to restart a container. +- `readiness`, that determines when a container is ready to start accepting traffic. When a pod is not ready, it is removed from the service load balancers. diff --git a/src/content/pages/ko/advanced/security-updates.mdx b/src/content/pages/ko/advanced/security-updates.mdx new file mode 100644 index 0000000000..dfed519ec6 --- /dev/null +++ b/src/content/pages/ko/advanced/security-updates.mdx @@ -0,0 +1,87 @@ +--- +title: Security updates +description: Review the latest security updates and patches for Express.js, including detailed vulnerability lists for different versions to help maintain a secure application. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Node.js vulnerabilities directly affect Express. Therefore, keep a watch on Node.js +vulnerabilities and make sure you are using the latest +stable version of Node.js. + + + +The list below enumerates the Express vulnerabilities that were fixed in the specified version update. + + + +If you believe you have discovered a security vulnerability in Express, please see Security +Policies and Procedures. + + + +## 4.x + +* 4.21.2 + * The dependency `path-to-regexp` has been updated to address a [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +* 4.21.1 + * The dependency `cookie` has been updated to address a [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), This may affect your application if you use `res.cookie`. +* 4.20.0 + * Fixed XSS vulnerability in `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + * The dependency `serve-static` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). + * The dependency `send` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + * The dependency `path-to-regexp` has been updated to address a [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + * The dependency `body-parser` has been updated to addres a [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), This may affect your application if you had url enconding activated. +* 4.19.0, 4.19.1 + * Fixed open redirect vulnerability in `res.location` and `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +* 4.17.3 + * The dependency `qs` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). This may affect your application if the following APIs are used: `req.query`, `req.body`, `req.param`. +* 4.16.0 + * The dependency `forwarded` has been updated to address a [vulnerability](https://npmjs.com/advisories/527). This may affect your application if the following APIs are used: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + * The dependency `mime` has been updated to address a [vulnerability](https://npmjs.com/advisories/535), but this issue does not impact Express. + * The dependency `send` has been updated to provide a protection against a [Node.js 8.5.0 vulnerability](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). This only impacts running Express on the specific Node.js version 8.5.0. +* 4.15.5 + * The dependency `debug` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:debug:20170905), but this issue does not impact Express. + * The dependency `fresh` has been updated to address a [vulnerability](https://npmjs.com/advisories/526). This will affect your application if the following APIs are used: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. +* 4.15.3 + * The dependency `ms` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:ms:20170412). This may affect your application if untrusted string input is passed to the `maxAge` option in the following APIs: `express.static`, `res.sendfile`, and `res.sendFile`. +* 4.15.2 + * The dependency `qs` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:qs:20170213), but this issue does not impact Express. Updating to 4.15.2 is a good practice, but not required to address the vulnerability. +* 4.11.1 + * Fixed root path disclosure vulnerability in `express.static`, `res.sendfile`, and `res.sendFile` +* 4.10.7 + * Fixed open redirect vulnerability in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 4.8.8 + * Fixed directory traversal vulnerabilities in `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +* 4.8.4 + * Node.js 0.10 can leak `fd`s in certain situations that affect `express.static` and `res.sendfile`. Malicious requests could cause `fd`s to leak and eventually lead to `EMFILE` errors and server unresponsiveness. +* 4.8.0 + * Sparse arrays that have extremely high indexes in the query string could cause the process to run out of memory and crash the server. + * Extremely nested query string objects could cause the process to block and make the server unresponsive temporarily. + +## 3.x + + +**Express 3.x IS END-OF-LIFE AND NO LONGER MAINTAINED** + +Known and unknown security and performance issues in 3.x have not been addressed since the last update (1 August, 2015). It is highly recommended to use the latest version of Express. + +If you are unable to upgrade past 3.x, please consider [Commercial Support Options](/en/support#commercial-support-options). + + + +* 3.19.1 + * Fixed root path disclosure vulnerability in `express.static`, `res.sendfile`, and `res.sendFile` +* 3.19.0 + * Fixed open redirect vulnerability in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 3.16.10 + * Fixed directory traversal vulnerabilities in `express.static`. +* 3.16.6 + * Node.js 0.10 can leak `fd`s in certain situations that affect `express.static` and `res.sendfile`. Malicious requests could cause `fd`s to leak and eventually lead to `EMFILE` errors and server unresponsiveness. +* 3.16.0 + * Sparse arrays that have extremely high indexes in query string could cause the process to run out of memory and crash the server. + * Extremely nested query string objects could cause the process to block and make the server unresponsive temporarily. +* 3.3.0 + * The 404 response of an unsupported method override attempt was susceptible to cross-site scripting attacks. diff --git a/src/content/pages/ko/guide/database-integration.mdx b/src/content/pages/ko/guide/database-integration.mdx new file mode 100644 index 0000000000..9a97d66c47 --- /dev/null +++ b/src/content/pages/ko/guide/database-integration.mdx @@ -0,0 +1,503 @@ +--- +title: Database integration +description: Discover how to integrate various databases with Express.js applications, including setup examples for MongoDB, MySQL, PostgreSQL, and more. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Adding the capability to connect databases to Express apps is just a matter of loading an appropriate Node.js driver for the database in your app. This document briefly explains how to add and use some of the most popular Node.js modules for database systems in your Express app: + +* [Cassandra](#cassandra) +* [Couchbase](#couchbase) +* [CouchDB](#couchdb) +* [LevelDB](#leveldb) +* [MySQL](#mysql) +* [MongoDB](#mongodb) +* [Neo4j](#neo4j) +* [Oracle](#oracle) +* [PostgreSQL](#postgresql) +* [Redis](#redis) +* [SQL Server](#sql-server) +* [SQLite](#sqlite) +* [Elasticsearch](#elasticsearch) + + + +These database drivers are among many that are available. For other options, search on the +[npm](https://www.npmjs.com/) site. + + + +## Cassandra + +**Module**: [cassandra-driver](https://github.com/datastax/nodejs-driver) + +### Installation + +```bash +$ npm install cassandra-driver +``` + +### Example + +```js +const cassandra = require('cassandra-driver'); +const client = new cassandra.Client({ contactPoints: ['localhost'] }); + +client.execute('select key from system.local', (err, result) => { + if (err) throw err; + console.log(result.rows[0]); +}); +``` + +## Couchbase + +**Module**: [couchnode](https://github.com/couchbase/couchnode) + +### Installation + +```bash +$ npm install couchbase +``` + +### Example + +```js +const couchbase = require('couchbase'); +const bucket = new couchbase.Cluster('http://localhost:8091').openBucket('bucketName'); + +// add a document to a bucket +bucket.insert('document-key', { name: 'Matt', shoeSize: 13 }, (err, result) => { + if (err) { + console.log(err); + } else { + console.log(result); + } +}); + +// get all documents with shoe size 13 +const n1ql = 'SELECT d.* FROM `bucketName` d WHERE shoeSize = $1'; +const query = N1qlQuery.fromString(n1ql); +bucket.query(query, [13], (err, result) => { + if (err) { + console.log(err); + } else { + console.log(result); + } +}); +``` + +## CouchDB + +**Module**: [nano](https://github.com/dscape/nano) + +### Installation + +```bash +$ npm install nano +``` + +### Example + +```js +const nano = require('nano')('http://localhost:5984'); +nano.db.create('books'); +const books = nano.db.use('books'); + +// Insert a book document in the books database +books.insert({ name: 'The Art of war' }, null, (err, body) => { + if (err) { + console.log(err); + } else { + console.log(body); + } +}); + +// Get a list of all books +books.list((err, body) => { + if (err) { + console.log(err); + } else { + console.log(body.rows); + } +}); +``` + +## LevelDB + +**Module**: [levelup](https://github.com/rvagg/node-levelup) + +### Installation + +```bash +$ npm install level levelup leveldown +``` + +### Example + +```js +const levelup = require('levelup'); +const db = levelup('./mydb'); + +db.put('name', 'LevelUP', (err) => { + if (err) return console.log('Ooops!', err); + + db.get('name', (err, value) => { + if (err) return console.log('Ooops!', err); + + console.log(`name=${value}`); + }); +}); +``` + +## MySQL + +**Module**: [mysql](https://github.com/felixge/node-mysql/) + +### Installation + +```bash +$ npm install mysql +``` + +### Example + +```js +const mysql = require('mysql'); +const connection = mysql.createConnection({ + host: 'localhost', + user: 'dbuser', + password: 's3kreee7', + database: 'my_db', +}); + +connection.connect(); + +connection.query('SELECT 1 + 1 AS solution', (err, rows, fields) => { + if (err) throw err; + + console.log('The solution is: ', rows[0].solution); +}); + +connection.end(); +``` + +## MongoDB + +**Module**: [mongodb](https://github.com/mongodb/node-mongodb-native) + +### Installation + +```bash +$ npm install mongodb +``` + +### Example (v2.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { + if (err) throw err; + + db.collection('mammals') + .find() + .toArray((err, result) => { + if (err) throw err; + + console.log(result); + }); +}); +``` + +### Example (v3.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, client) => { + if (err) throw err; + + const db = client.db('animals'); + + db.collection('mammals') + .find() + .toArray((err, result) => { + if (err) throw err; + + console.log(result); + }); +}); +``` + +If you want an object model driver for MongoDB, look at [Mongoose](https://github.com/LearnBoost/mongoose). + +## Neo4j + +**Module**: [neo4j-driver](https://github.com/neo4j/neo4j-javascript-driver) + +### Installation + +```bash +$ npm install neo4j-driver +``` + +### Example + +```js +const neo4j = require('neo4j-driver'); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth.basic('neo4j', 'letmein')); + +const session = driver.session(); + +session.readTransaction((tx) => { + return tx + .run('MATCH (n) RETURN count(n) AS count') + .then((res) => { + console.log(res.records[0].get('count')); + }) + .catch((error) => { + console.log(error); + }); +}); +``` + +## Oracle + +**Module**: [oracledb](https://github.com/oracle/node-oracledb) + +### Installation + +NOTE: [See installation prerequisites](https://github.com/oracle/node-oracledb#-installation). + +```bash +$ npm install oracledb +``` + +### Example + +```js +const oracledb = require('oracledb'); +const config = { + user: '', + password: '', + connectString: 'localhost:1521/orcl', +}; + +async function getEmployee(empId) { + let conn; + + try { + conn = await oracledb.getConnection(config); + + const result = await conn.execute('select * from employees where employee_id = :id', [empId]); + + console.log(result.rows[0]); + } catch (err) { + console.log('Ouch!', err); + } finally { + if (conn) { + // conn assignment worked, need to close + await conn.close(); + } + } +} + +getEmployee(101); +``` + +## PostgreSQL + +**Module**: [pg-promise](https://github.com/vitaly-t/pg-promise) + +### Installation + +```bash +$ npm install pg-promise +``` + +### Example + +```js +const pgp = require('pg-promise')(/* options */); +const db = pgp('postgres://username:password@host:port/database'); + +db.one('SELECT $1 AS value', 123) + .then((data) => { + console.log('DATA:', data.value); + }) + .catch((error) => { + console.log('ERROR:', error); + }); +``` + +## Redis + +**Module**: [redis](https://github.com/mranney/node_redis) + +### Installation + +```bash +$ npm install redis +``` + +### Example + +```js +const redis = require('redis'); +const client = redis.createClient(); + +client.on('error', (err) => { + console.log(`Error ${err}`); +}); + +client.set('string key', 'string val', redis.print); +client.hset('hash key', 'hashtest 1', 'some value', redis.print); +client.hset(['hash key', 'hashtest 2', 'some other value'], redis.print); + +client.hkeys('hash key', (err, replies) => { + console.log(`${replies.length} replies:`); + + replies.forEach((reply, i) => { + console.log(` ${i}: ${reply}`); + }); + + client.quit(); +}); +``` + +## SQL Server + +**Module**: [tedious](https://github.com/tediousjs/tedious) + +### Installation + +```bash +$ npm install tedious +``` + +### Example + +```js +const Connection = require('tedious').Connection; +const Request = require('tedious').Request; + +const config = { + server: 'localhost', + authentication: { + type: 'default', + options: { + userName: 'your_username', // update me + password: 'your_password', // update me + }, + }, +}; + +const connection = new Connection(config); + +connection.on('connect', (err) => { + if (err) { + console.log(err); + } else { + executeStatement(); + } +}); + +function executeStatement() { + request = new Request("select 123, 'hello world'", (err, rowCount) => { + if (err) { + console.log(err); + } else { + console.log(`${rowCount} rows`); + } + connection.close(); + }); + + request.on('row', (columns) => { + columns.forEach((column) => { + if (column.value === null) { + console.log('NULL'); + } else { + console.log(column.value); + } + }); + }); + + connection.execSql(request); +} +``` + +## SQLite + +**Module**: [sqlite3](https://github.com/mapbox/node-sqlite3) + +### Installation + +```bash +$ npm install sqlite3 +``` + +### Example + +```js +const sqlite3 = require('sqlite3').verbose(); +const db = new sqlite3.Database(':memory:'); + +db.serialize(() => { + db.run('CREATE TABLE lorem (info TEXT)'); + const stmt = db.prepare('INSERT INTO lorem VALUES (?)'); + + for (let i = 0; i < 10; i++) { + stmt.run(`Ipsum ${i}`); + } + + stmt.finalize(); + + db.each('SELECT rowid AS id, info FROM lorem', (err, row) => { + console.log(`${row.id}: ${row.info}`); + }); +}); + +db.close(); +``` + +## Elasticsearch + +**Module**: [elasticsearch](https://github.com/elastic/elasticsearch-js) + +### Installation + +```bash +$ npm install elasticsearch +``` + +### Example + +```js +const elasticsearch = require('elasticsearch'); +const client = elasticsearch.Client({ + host: 'localhost:9200', +}); + +client + .search({ + index: 'books', + type: 'book', + body: { + query: { + multi_match: { + query: 'express js', + fields: ['title', 'description'], + }, + }, + }, + }) + .then( + (response) => { + const hits = response.hits.hits; + }, + (error) => { + console.trace(error.message); + } + ); +``` diff --git a/src/content/pages/ko/guide/migrating-4.mdx b/src/content/pages/ko/guide/migrating-4.mdx new file mode 100644 index 0000000000..619682818a --- /dev/null +++ b/src/content/pages/ko/guide/migrating-4.mdx @@ -0,0 +1,662 @@ +--- +title: Moving to Express 4 +description: A guide to migrating your Express.js applications from version 3 to 4, covering changes in middleware, routing, and how to update your codebase effectively. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express 4 is a breaking change from Express 3. That means an existing Express 3 app will *not* work if you update the Express version in its dependencies. + +This article covers: + + + +## Changes in Express 4 + +There are several significant changes in Express 4: + + + +See also: + +* [New features in 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +* [Migrating from 3.x to 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) + +### Changes to Express core and middleware system + +Express 4 no longer depends on Connect, and removes all built-in +middleware from its core, except for the `express.static` function. This means that +Express is now an independent routing and middleware web framework, and +Express versioning and releases are not affected by middleware updates. + +Without built-in middleware, you must explicitly add all the +middleware that is required to run your app. Simply follow these steps: + +1. Install the module: `npm install --save ` +2. In your app, require the module: `require('module-name')` +3. Use the module according to its documentation: `app.use( ... )` + +The following table lists Express 3 middleware and their counterparts in Express 4. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Express 3Express 4
+ express.bodyParser + + body-parser + + multer +
+ express.compress + + compression +
+ express.cookieSession + + cookie-session +
+ express.cookieParser + + cookie-parser +
+ express.logger + + morgan +
+ express.session + + express-session +
+ express.favicon + + serve-favicon +
+ express.responseTime + + response-time +
+ express.errorHandler + + errorhandler +
+ express.methodOverride + + method-override +
+ express.timeout + + connect-timeout +
+ express.vhost + + vhost +
+ express.csrf + + csurf +
+ express.directory + + serve-index +
+ express.static + + serve-static +
+ +Here is the [complete list](https://github.com/senchalabs/connect#middleware) of Express 4 middleware. + +In most cases, you can simply replace the old version 3 middleware with +its Express 4 counterpart. For details, see the module documentation in +GitHub. + +#### `app.use` accepts parameters + +In version 4 you can use a variable parameter to define the path where middleware functions are loaded, then read the value of the parameter from the route handler. +For example: + +```js +app.use('/book/:id', (req, res, next) => { + console.log('ID:', req.params.id); + next(); +}); +``` + +### The routing system + +Apps now implicitly load routing middleware, so you no longer have to +worry about the order in which middleware is loaded with respect to +the `router` middleware. + +The way you define routes is unchanged, but the routing system has two +new features to help organize your routes: + +* A new method, `app.route()`, to create chainable route handlers for a route path. +* A new class, `express.Router`, to create modular mountable route handlers. + +#### `app.route()` method + +The new `app.route()` method enables you to create chainable route handlers +for a route path. Because the path is specified in a single location, creating modular routes is helpful, as is reducing redundancy and typos. For more +information about routes, see [`Router()` documentation](/en/4x/api#router). + +Here is an example of chained route handlers that are defined by using the `app.route()` function. + +```js +app + .route('/book') + .get((req, res) => { + res.send('Get a random book'); + }) + .post((req, res) => { + res.send('Add a book'); + }) + .put((req, res) => { + res.send('Update the book'); + }); +``` + +#### `express.Router` class + +The other feature that helps to organize routes is a new class, +`express.Router`, that you can use to create modular mountable +route handlers. A `Router` instance is a complete middleware and +routing system; for this reason it is often referred to as a "mini-app". + +The following example creates a router as a module, loads middleware in +it, defines some routes, and mounts it on a path on the main app. + +For example, create a router file named `birds.js` in the app directory, +with the following content: + +```js +var express = require('express'); +var router = express.Router(); + +// middleware specific to this router +router.use((req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}); +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Then, load the router module in the app: + +```js +var birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +The app will now be able to handle requests to the `/birds` and +`/birds/about` paths, and will call the `timeLog` +middleware that is specific to the route. + +### Other changes + +The following table lists other small but important changes in Express 4: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ObjectDescription
Node.jsExpress 4 requires Node.js 0.10.x or later and has dropped support for Node.js 0.8.x.
`http.createServer()` + The `http` module is no longer needed, unless you need to directly work with it + (socket.io/SPDY/HTTPS). The app can be started by using the `app.listen()` function. +
`app.configure()` + The `app.configure()` function has been removed. Use the `process.env.NODE_ENV` or + `app.get('env')` function to detect the environment and configure the app accordingly. +
`json spaces` + The `json spaces` application property is disabled by default in Express 4. +
`req.accepted()` + Use `req.accepts()`, `req.acceptsEncodings()`, `req.acceptsCharsets()`, and + `req.acceptsLanguages()`. +
`res.location()`No longer resolves relative URLs.
`req.params`Was an array; now an object.
`res.locals`Was a function; now an object.
`res.headerSent`Changed to `res.headersSent`.
`app.route`Now available as `app.mountpath`.
`res.on('header')`Removed.
`res.charset`Removed.
`res.setHeader('Set-Cookie', val)` + Functionality is now limited to setting the basic cookie value. Use `res.cookie()` for added + functionality. +
+ +## Example app migration + +Here is an example of migrating an Express 3 application to Express 4. +The files of interest are `app.js` and `package.json`. + +### Version 3 app + +#### `app.js` + +Consider an Express v.3 application with the following `app.js` file: + +```js +var express = require('express'); +var routes = require('./routes'); +var user = require('./routes/user'); +var http = require('http'); +var path = require('path'); + +var app = express(); + +// all environments +app.set('port', process.env.PORT || 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(express.favicon()); +app.use(express.logger('dev')); +app.use(express.methodOverride()); +app.use(express.session({ secret: 'your secret here' })); +app.use(express.bodyParser()); +app.use(app.router); +app.use(express.static(path.join(__dirname, 'public'))); + +// development only +if (app.get('env') === 'development') { + app.use(express.errorHandler()); +} + +app.get('/', routes.index); +app.get('/users', user.list); + +http.createServer(app).listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + +#### `package.json` + +The accompanying version 3 `package.json` file might look +something like this: + +```json +{ + "name": "application-name", + "version": "0.0.1", + "private": true, + "scripts": { + "start": "node app.js" + }, + "dependencies": { + "express": "3.12.0", + "pug": "*" + } +} +``` + +### Process + +Begin the migration process by installing the required middleware for the +Express 4 app and updating Express and Pug to their respective latest +version with the following command: + +```bash +$ npm install serve-favicon morgan method-override express-session body-parser multer errorhandler express@latest pug@latest --save +``` + +Make the following changes to `app.js`: + +1. The built-in Express middleware functions `express.favicon`, + `express.logger`, `express.methodOverride`, + `express.session`, `express.bodyParser` and + `express.errorHandler` are no longer available on the + `express` object. You must install their alternatives + manually and load them in the app. + +2. You no longer need to load the `app.router` function. + It is not a valid Express 4 app object, so remove the + `app.use(app.router);` code. + +3. Make sure that the middleware functions are loaded in the correct order - load `errorHandler` after loading the app routes. + +### Version 4 app + +#### `package.json` + +Running the above `npm` command will update `package.json` as follows: + +```json +{ + "name": "application-name", + "version": "0.0.1", + "private": true, + "scripts": { + "start": "node app.js" + }, + "dependencies": { + "body-parser": "^1.5.2", + "errorhandler": "^1.1.1", + "express": "^4.8.0", + "express-session": "^1.7.2", + "pug": "^2.0.0", + "method-override": "^2.1.2", + "morgan": "^1.2.2", + "multer": "^0.1.3", + "serve-favicon": "^2.0.1" + } +} +``` + +#### `app.js` + +Then, remove invalid code, load the required middleware, and make other +changes as necessary. The `app.js` file will look like this: + +```js +var http = require('http'); +var express = require('express'); +var routes = require('./routes'); +var user = require('./routes/user'); +var path = require('path'); + +var favicon = require('serve-favicon'); +var logger = require('morgan'); +var methodOverride = require('method-override'); +var session = require('express-session'); +var bodyParser = require('body-parser'); +var multer = require('multer'); +var errorHandler = require('errorhandler'); + +var app = express(); + +// all environments +app.set('port', process.env.PORT || 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(favicon(path.join(__dirname, '/public/favicon.ico'))); +app.use(logger('dev')); +app.use(methodOverride()); +app.use( + session({ + resave: true, + saveUninitialized: true, + secret: 'uwotm8', + }) +); +app.use(bodyParser.json()); +app.use(bodyParser.urlencoded({ extended: true })); +app.use(multer()); +app.use(express.static(path.join(__dirname, 'public'))); + +app.get('/', routes.index); +app.get('/users', user.list); + +// error handling middleware should be loaded after the loading the routes +if (app.get('env') === 'development') { + app.use(errorHandler()); +} + +var server = http.createServer(app); +server.listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + + +Unless you need to work directly with the `http` module (socket.io/SPDY/HTTPS), loading it is not required, and the app can be simply started this way: + +```js +app.listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + + + +### Run the app + +The migration process is complete, and the app is now an +Express 4 app. To confirm, start the app by using the following command: + +```bash +$ node . +``` + +Load [http://localhost:3000](http://localhost:3000) +and see the home page being rendered by Express 4. + +## Upgrading to the Express 4 app generator + +The command-line tool to generate an Express app is still +`express`, but to upgrade to the new version, you must uninstall +the Express 3 app generator and then install the new +`express-generator`. + +### Installing + +If you already have the Express 3 app generator installed on your system, +you must uninstall it: + +```bash +$ npm uninstall -g express +``` + +Depending on how your file and directory privileges are configured, +you might need to run this command with `sudo`. + +Now install the new generator: + +```bash +$ npm install -g express-generator +``` + +Depending on how your file and directory privileges are configured, +you might need to run this command with `sudo`. + +Now the `express` command on your system is updated to the +Express 4 generator. + +### Changes to the app generator + +Command options and use largely remain the same, with the following exceptions: + +* Removed the `--sessions` option. +* Removed the `--jshtml` option. +* Added the `--hogan` option to support [Hogan.js](http://twitter.github.io/hogan.js/). + +### Example + +Execute the following command to create an Express 4 app: + +```bash +$ express app4 +``` + +If you look at the contents of the `app4/app.js` file, you will notice +that all the middleware functions (except `express.static`) that are required for +the app are loaded as independent modules, and the `router` middleware +is no longer explicitly loaded in the app. + +You will also notice that the `app.js` file is now a Node.js module, in contrast to the standalone app that was generated by the old generator. + +After installing the dependencies, start the app by using the following command: + +```bash +$ npm start +``` + +If you look at the `npm start` script in the `package.json` file, +you will notice that the actual command that starts the app is +`node ./bin/www`, which used to be `node app.js` +in Express 3. + +Because the `app.js` file that was generated by the Express 4 generator +is now a Node.js module, it can no longer be started independently as an app +(unless you modify the code). The module must be loaded in a Node.js file +and started via the Node.js file. The Node.js file is `./bin/www` +in this case. + +Neither the `bin` directory nor the extensionless `www` +file is mandatory for creating an Express app or starting the app. They are +just suggestions made by the generator, so feel free to modify them to suit your +needs. + +To get rid of the `www` directory and keep things the "Express 3 way", +delete the line that says `module.exports = app;` at the end of the +`app.js` file, then paste the following code in its place: + +```js +app.set('port', process.env.PORT || 3000); + +var server = app.listen(app.get('port'), () => { + debug('Express server listening on port ' + server.address().port); +}); +``` + +Ensure that you load the `debug` module at the top of the `app.js` file by using the following code: + +```js +var debug = require('debug')('app4'); +``` + +Next, change `"start": "node ./bin/www"` in the `package.json` file to `"start": "node app.js"`. + +You have now moved the functionality of `./bin/www` back to +`app.js`. This change is not recommended, but the exercise helps you +to understand how the `./bin/www` file works, and why the `app.js` file +no longer starts on its own. diff --git a/src/content/pages/ko/guide/migrating-5.mdx b/src/content/pages/ko/guide/migrating-5.mdx new file mode 100644 index 0000000000..2a035c4e04 --- /dev/null +++ b/src/content/pages/ko/guide/migrating-5.mdx @@ -0,0 +1,678 @@ +--- +title: Moving to Express 5 +description: A comprehensive guide to migrating your Express.js applications from version 4 to 5, detailing breaking changes, deprecated methods, and new improvements. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express 5 is not very different from Express 4; although it maintains the same basic API, there are still changes that break compatibility with the previous version. Therefore, an application built with Express 4 might not work if you update it to use Express 5. + +To install this version, you need to have a Node.js version 18 or higher. Then, execute the following command in your application directory: + +```sh +npm install "express@5" +``` + +You can then run your automated tests to see what fails, and fix problems according to the updates listed below. After addressing test failures, run your app to see what errors occur. You'll find out right away if the app uses any methods or properties that are not supported. + +## Express 5 Codemods + +To help you migrate your express server, we have created a set of codemods that will help you automatically update your code to the latest version of Express. + +Run the following command for run all the codemods available: + +```sh +npx codemod@latest @expressjs/v5-migration-recipe +``` + +If you want to run a specific codemod, you can run the following command: + +```sh +npx codemod@latest @expressjs/name-of-the-codemod +``` + +You can find the list of available codemods [here](https://codemod.link/express). + +## Changes in Express 5 + +**Removed methods and properties** + + + +**Changed** + + + +**Improvements** + + + +## Removed methods and properties + +If you use any of these methods or properties in your app, it will crash. So, you'll need to change your app after you update to version 5. + +### app.del() + +Express 5 no longer supports the `app.del()` function. If you use this function, an error is thrown. For registering HTTP DELETE routes, use the `app.delete()` function instead. + +Initially, `del` was used instead of `delete`, because `delete` is a reserved keyword in JavaScript. However, as of ECMAScript 6, `delete` and other reserved keywords can legally be used as property names. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/route-del-to-delete +``` + + + +```js +// v4 +app.del('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); + +// v5 +app.delete('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); +``` + +### app.param(fn) + +The `app.param(fn)` signature was used for modifying the behavior of the `app.param(name, fn)` function. It has been deprecated since v4.11.0, and Express 5 no longer supports it at all. + +### Pluralized method names + +The following method names have been pluralized. In Express 4, using the old methods resulted in a deprecation warning. Express 5 no longer supports them at all: + +`req.acceptsCharset()` is replaced by `req.acceptsCharsets()`. + +`req.acceptsEncoding()` is replaced by `req.acceptsEncodings()`. + +`req.acceptsLanguage()` is replaced by `req.acceptsLanguages()`. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/pluralize-method-names +``` + + + +```js +// v4 +app.all('/', (req, res) => { + req.acceptsCharset('utf-8'); + req.acceptsEncoding('br'); + req.acceptsLanguage('en'); + + // ... +}); + +// v5 +app.all('/', (req, res) => { + req.acceptsCharsets('utf-8'); + req.acceptsEncodings('br'); + req.acceptsLanguages('en'); + + // ... +}); +``` + +### Leading colon (:) in the name for app.param(name, fn) + +A leading colon character (:) in the name for the `app.param(name, fn)` function is a remnant of Express 3, and for the sake of backwards compatibility, Express 4 supported it with a deprecation notice. Express 5 will silently ignore it and use the name parameter without prefixing it with a colon. + +This should not affect your code if you follow the Express 4 documentation of [app.param](/en/4x/api#app.param), as it makes no mention of the leading colon. + +### req.param(name) + +This potentially confusing and dangerous method of retrieving form data has been removed. You will now need to specifically look for the submitted parameter name in the `req.params`, `req.body`, or `req.query` object. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/explicit-request-params +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + const id = req.param('id'); + const body = req.param('body'); + const query = req.param('query'); + + // ... +}); + +// v5 +app.post('/user', (req, res) => { + const id = req.params.id; + const body = req.body; + const query = req.query; + + // ... +}); +``` + +### res.json(obj, status) + +Express 5 no longer supports the signature `res.json(obj, status)`. Instead, set the status and then chain it to the `res.json()` method like this: `res.status(status).json(obj)`. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.json({ name: 'Ruben' }, 201); +}); + +// v5 +app.post('/user', (req, res) => { + res.status(201).json({ name: 'Ruben' }); +}); +``` + +### res.jsonp(obj, status) + +Express 5 no longer supports the signature `res.jsonp(obj, status)`. Instead, set the status and then chain it to the `res.jsonp()` method like this: `res.status(status).jsonp(obj)`. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.jsonp({ name: 'Ruben' }, 201); +}); + +// v5 +app.post('/user', (req, res) => { + res.status(201).jsonp({ name: 'Ruben' }); +}); +``` + +### res.redirect(url, status) + +Express 5 no longer supports the signature `res.redirect(url, status)`. Instead, use the following signature: `res.redirect(status, url)`. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/redirect-arg-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('/users', 301); +}); + +// v5 +app.get('/user', (req, res) => { + res.redirect(301, '/users'); +}); +``` + +### res.redirect('back') and res.location('back') + +Express 5 no longer supports the magic string `back` in the `res.redirect()` and `res.location()` methods. Instead, use the `req.get('Referrer') || '/'` value to redirect back to the previous page. In Express 4, the `res.redirect('back')` and `res.location('back')` methods were deprecated. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/back-redirect-deprecated +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('back'); +}); + +// v5 +app.get('/user', (req, res) => { + res.redirect(req.get('Referrer') || '/'); +}); +``` + +### res.send(body, status) + +Express 5 no longer supports the signature `res.send(obj, status)`. Instead, set the status and then chain it to the `res.send()` method like this: `res.status(status).send(obj)`. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send({ name: 'Ruben' }, 200); +}); + +// v5 +app.get('/user', (req, res) => { + res.status(200).send({ name: 'Ruben' }); +}); +``` + +### res.send(status) + +Express 5 no longer supports the signature `res.send(status)`, where `status` is a number. Instead, use the `res.sendStatus(statusCode)` function, which sets the HTTP response header status code and sends the text version of the code: "Not Found", "Internal Server Error", and so on. +If you need to send a number by using the `res.send()` function, quote the number to convert it to a string, so that Express does not interpret it as an attempt to use the unsupported old signature. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send(200); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendStatus(200); +}); +``` + +### res.sendfile() + +The `res.sendfile()` function has been replaced by a camel-cased version `res.sendFile()` in Express 5. + +**Note:** In Express 5, `res.sendFile()` uses the `mime-types` package for MIME type detection, which returns different Content-Type values than Express 4 for several common file types: + +* JavaScript files (.js): now "text/javascript" instead of "application/javascript" +* JSON files (.json): now "application/json" instead of "text/json" +* CSS files (.css): now "text/css" instead of "text/plain" +* XML files (.xml): now "application/xml" instead of "text/xml" +* Font files (.woff): now "font/woff" instead of "application/font-woff" +* SVG files (.svg): now "image/svg+xml" instead of "application/svg+xml" + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/camelcase-sendfile +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.sendfile('/path/to/file'); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendFile('/path/to/file'); +}); +``` + +### router.param(fn) + +The `router.param(fn)` signature was used for modifying the behavior of the `router.param(name, fn)` function. It has been deprecated since v4.11.0, and Express 5 no longer supports it at all. + +### express.static.mime + +In Express 5, `mime` is no longer an exported property of the `static` field. +Use the [`mime-types` package](https://github.com/jshttp/mime-types) to work with MIME type values. + +**Important:** This change affects not only direct usage of `express.static.mime` but also other Express methods that rely on MIME type detection, such as `res.sendFile()`. The following MIME types have changed from Express 4: + +* JavaScript files (.js): now served as "text/javascript" instead of "application/javascript" +* JSON files (.json): now served as "application/json" instead of "text/json" +* CSS files (.css): now served as "text/css" instead of "text/plain" +* HTML files (): now served as "text/html; charset=utf-8" instead of just "text/html" +* XML files (.xml): now served as "application/xml" instead of "text/xml" +* Font files (.woff): now served as "font/woff" instead of "application/font-woff" + +```js +// v4 +express.static.mime.lookup('json'); + +// v5 +const mime = require('mime-types'); +mime.lookup('json'); +``` + +### express:router debug logs + +In Express 5, router handling logic is performed by a dependency. Therefore, the +debug logs for the router are no longer available under the `express:` namespace. +In v4, the logs were available under the namespaces `express:router`, `express:router:layer`, +and `express:router:route`. All of these were included under the namespace `express:*`. +In v5.1+, the logs are available under the namespaces `router`, `router:layer`, and `router:route`. +The logs from `router:layer` and `router:route` are included in the namespace `router:*`. +To achieve the same detail of debug logging when using `express:*` in v4, use a conjunction of +`express:*`, `router`, and `router:*`. + +```sh + +DEBUG=express:* node index.js + + +DEBUG=express:*,router,router:* node index.js +``` + +## Changed + +### Path route matching syntax + +Path route matching syntax is when a string is supplied as the first parameter to the `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, and `router.use()` APIs. The following changes have been made to how the path string is matched to an incoming request: + +* The wildcard `*` must have a name, matching the behavior of parameters `:`, use `/*splat` instead of `/*` + +```js +// v4 +app.get('/*', async (req, res) => { + res.send('ok'); +}); + +// v5 +app.get('/*splat', async (req, res) => { + res.send('ok'); +}); +``` + + +`*splat` matches any path without the root path. If you need to match the root path as well `/`, you can use `/{*splat}`, wrapping the wildcard in braces. + +```js +// v5 +app.get('/{*splat}', async (req, res) => { + res.send('ok'); +}); +``` + + + +* The optional character `?` is no longer supported, use braces instead. + +```js +// v4 +app.get('/:file.:ext?', async (req, res) => { + res.send('ok'); +}); + +// v5 +app.get('/:file{.:ext}', async (req, res) => { + res.send('ok'); +}); +``` + +* Regexp characters are not supported. For example: + +```js +app.get('/[discussion|page]/:slug', async (req, res) => { + res.status(200).send('ok'); +}); +``` + +should be changed to: + +```js +app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { + res.status(200).send('ok'); +}); +``` + +* Some characters have been reserved to avoid confusion during upgrade (`()[]?+!`), use `\` to escape them. +* Parameter names now support valid JavaScript identifiers, or quoted like `:"this"`. + +### Rejected promises handled from middleware and handlers + +Request middleware and handlers that return rejected promises are now handled by forwarding the rejected value as an `Error` to the error handling middleware. This means that using `async` functions as middleware and handlers are easier than ever. When an error is thrown in an `async` function or a rejected promise is `await`ed inside an async function, those errors will be passed to the error handler as if calling `next(err)`. + +Details of how Express handles errors is covered in the [error handling documentation](/en/guide/error-handling). + +### express.urlencoded + +The `express.urlencoded` method makes the `extended` option `false` by default. + +### express.static dotfiles + +In Express 5, the `express.static` middleware's `dotfiles` option now defaults to `"ignore"`. This is a change from Express 4, where dotfiles were served by default. As a result, files inside a directory that starts with a dot (`.`), such as `.well-known`, will no longer be accessible and will return a **404 Not Found** error. This can break functionality that depends on serving dot-directories, such as Android App Links, and Apple Universal Links. + +Example of breaking code: + +```js +// v4 +app.use(express.static('public')); +``` + +After migrating to Express 5, a request to `/.well-known/assetlinks.json` will result in a **404 Not Found**. + +To fix this, serve specific dot-directories explicitly using the `dotfiles: "allow"` option: + +```js +// v5 +app.use('/.well-known', express.static('public/.well-known', { dotfiles: 'allow' })); +app.use(express.static('public')); +``` + +This approach allows you to safely serve only the intended dot-directories while keeping the default secure behavior for other dotfiles, which remain inaccessible. + +### app.listen + +In Express 5, the `app.listen` method will invoke the user-provided callback function (if provided) when the server receives an error event. In Express 4, such errors would be thrown. This change shifts error-handling responsibility to the callback function in Express 5. If there is an error, it will be passed to the callback as an argument. +For example: + +```js +const server = app.listen(8080, '0.0.0.0', (error) => { + if (error) { + throw error; // e.g. EADDRINUSE + } + console.log(`Listening on ${JSON.stringify(server.address())}`); +}); +``` + +### app.router + +The `app.router` object, which was removed in Express 4, has made a comeback in Express 5. In the new version, this object is a just a reference to the base Express router, unlike in Express 3, where an app had to explicitly load it. + +### req.body + +The `req.body` property returns `undefined` when the body has not been parsed. In Express 4, it returns `{}` by default. + +### req.host + +In Express 4, the `req.host` function incorrectly stripped off the port number if it was present. In Express 5, the port number is maintained. + +### req.params + +The `req.params` object now has a **null prototype** when using string paths. However, if the path is defined with a regular expression, `req.params` remains a standard object with a normal prototype. Additionally, there are two important behavioral changes: + +**Wildcard parameters are now arrays:** + +Wildcards (e.g., `/*splat`) capture path segments as an array instead of a single string. + +```js +app.get('/*splat', (req, res) => { + // GET /foo/bar + console.dir(req.params); + // => [Object: null prototype] { splat: [ 'foo', 'bar' ] } +}); +``` + +**Unmatched parameters are omitted:** + +In Express 4, unmatched wildcards were empty strings (`''`) and optional `:` parameters (using `?`) had a key with value `undefined`. In Express 5, unmatched parameters are completely omitted from `req.params`. + +```js +// v4: unmatched wildcard is empty string +app.get('/*', (req, res) => { + // GET / + console.dir(req.params); + // => { '0': '' } +}); + +// v4: unmatched optional param is undefined +app.get('/:file.:ext?', (req, res) => { + // GET /image + console.dir(req.params); + // => { file: 'image', ext: undefined } +}); + +// v5: unmatched optional param is omitted +app.get('/:file{.:ext}', (req, res) => { + // GET /image + console.dir(req.params); + // => [Object: null prototype] { file: 'image' } +}); +``` + +### req.query + +The `req.query` property is no longer a writable property and is instead a getter. The default query parser has been changed from "extended" to "simple". + +### res.clearCookie + +The `res.clearCookie` method ignores the `maxAge` and `expires` options provided by the user. + +### res.status + +The `res.status` method only accepts integers in the range of `100` to `999`, following the behavior defined by Node.js, and it returns an error when the status code is not an integer. + +### res.vary + +The `res.vary` throws an error when the `field` argument is missing. In Express 4, if the argument was omitted, it gave a warning in the console + +## Improvements + +### res.render() + +This method now enforces asynchronous behavior for all view engines, avoiding bugs caused by view engines that had a synchronous implementation and that violated the recommended interface. + +### Brotli encoding support + +Express 5 supports Brotli encoding for requests received from clients that support it. diff --git a/src/content/pages/ko/resources/glossary.mdx b/src/content/pages/ko/resources/glossary.mdx new file mode 100644 index 0000000000..e94e59ab60 --- /dev/null +++ b/src/content/pages/ko/resources/glossary.mdx @@ -0,0 +1,61 @@ +--- +title: Glossary +description: A comprehensive glossary of terms related to Express.js, Node.js, middleware, routing, and other key concepts to help you understand and use Express effectively. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +### application + +In general, one or more programs that are designed to carry out operations for a specific purpose. In the context of Express, a program that uses the Express API running on the Node.js platform. Might also refer to an [app object](/en/api#express). + +### API + +Application programming interface. Spell out the abbreviation when it is first used. + +### Express + +A fast, un-opinionated, minimalist web framework for Node.js applications. In general, "Express" is preferred to "Express.js," though the latter is acceptable. + +### libuv + +A multi-platform support library which focuses on asynchronous I/O, primarily developed for use by Node.js. + +### middleware + +A function that is invoked by the Express routing layer before the final request handler, and thus sits in the middle between a raw request and the final intended route. A few fine points of terminology around middleware: + +* `var foo = require('middleware')` is called *requiring* or *using* a Node.js module. Then the statement `var mw = foo()` typically returns the middleware. +* `app.use(mw)` is called *adding the middleware to the global processing stack*. +* `app.get('/foo', mw, function (req, res) { ... })` is called *adding the middleware to the "GET /foo" processing stack*. + +### Node.js + +A software platform that is used to build scalable network applications. Node.js uses JavaScript as its scripting language, and achieves high throughput via non-blocking I/O and a single-threaded event loop. See [nodejs.org](https://nodejs.org/en/). **Usage note**: Initially, "Node.js," thereafter "Node". + +### open-source, open source + +When used as an adjective, hyphenate; for example: "This is open-source software." See [Open-source software on Wikipedia](http://en.wikipedia.org/wiki/Open-source_software). + + + +Although it is common not to hyphenate this term, we are using the standard English rules for +hyphenating a compound adjective. + + + +### request + +An HTTP request. A client submits an HTTP request message to a server, which returns a response. The request must use one of several [request methods](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) such as GET, POST, and so on. + +### response + +An HTTP response. A server returns an HTTP response message to the client. The response contains completion status information about the request and might also contain requested content in its message body. + +### route + +Part of a URL that identifies a resource. For example, in `http://foo.com/products/id`, "/products/id" is the route. + +### router + +See [router](/en/api#router) in the API reference. diff --git a/src/content/pages/ko/resources/utils.md b/src/content/pages/ko/resources/utils.md new file mode 100644 index 0000000000..3a8b0a5be1 --- /dev/null +++ b/src/content/pages/ko/resources/utils.md @@ -0,0 +1,22 @@ +--- +title: Express utilities +description: Discover utility modules related to Express.js and Node.js, including tools for cookies, CSRF protection, URL parsing, routing, and more to enhance your applications. +--- + +## Express utility functions + +The [pillarjs](https://github.com/pillarjs) GitHub organization contains a number of modules +for utility functions that may be generally useful. + +| Utility modules | Description | +| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [cookies](https://www.npmjs.com/package/cookies) | Get and set HTTP(S) cookies that can be signed to prevent tampering, using Keygrip. Can be used with the Node.js HTTP library or as Express middleware. | +| [csrf](https://www.npmjs.com/package/csrf) | Contains the logic behind CSRF token creation and verification. Use this module to create custom CSRF middleware. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Function to invoke as the final step to respond to HTTP request. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Parse a URL with caching. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Turn an Express-style path string such as \`\`/user/:name\` into a regular expression. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Resolves a relative path against a root path with validation. | +| [router](https://www.npmjs.com/package/router) | Simple middleware-style router. | +| [send](https://www.npmjs.com/package/send) | Library for streaming files as a HTTP response, with support for partial responses (ranges), conditional-GET negotiation, and granular events. | + +For additional low-level HTTP-related modules, see [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/ko/support.md b/src/content/pages/ko/support.md new file mode 100644 index 0000000000..68763b76f0 --- /dev/null +++ b/src/content/pages/ko/support.md @@ -0,0 +1,23 @@ +--- +title: Version Support +description: Find information about the support schedule for different Express.js versions, including which versions are currently maintained and end-of-life policies. +--- + +Only the latest version of any given major release line is supported. + +Versions that are EOL (end-of-life) _may_ receive updates for critical security vulnerabilities, but the Express team offers no guarantee and does not plan to address or release fixes for any issues found. + +| Major Version | Minimum Node.js Version | Support Start Date | Support End Date | +| ------------------------------------------- | --------------------------------------- | ------------------ | ---------------- | +| [**v5.x**](/en/5x/api) | 18 | September 2024 | **ongoing** | +| [**v4.x**](/en/4x/api) | 0.10.0 | April 2014 | **ongoing** | +| [**v3.x**](/en/3x/api) | 0.8.0 | October 2012 | July 2015 | +| [**v2.x**](/2x/) | 0.4.1 | March 2011 | July 2012 | +| **v1.x** | 0.2.0 | December 2010 | March 2011 | +| **v0.14.x** | 0.1.98 | December 2010 | December 2010 | + +## Commercial Support Options + +If you are unable to update to a supported version of Express, please contact one of our partners to receive security updates: + +- [HeroDevs Never-Ending Support](http://www.herodevs.com/support/express-nes?utm_source=expressjs&utm_medium=link&utm_campaign=express_eol_page) diff --git a/src/content/pages/pt-br/advanced/best-practice-performance.md b/src/content/pages/pt-br/advanced/best-practice-performance.md new file mode 100644 index 0000000000..cc86d01356 --- /dev/null +++ b/src/content/pages/pt-br/advanced/best-practice-performance.md @@ -0,0 +1,305 @@ +--- +title: 'Práticas de produção: desempenho e confiabilidade' +description: Descubra desempenho e confiabilidade melhores práticas para aplicativos Express na produção, cobrindo otimizações de código e configurações de ambiente para um desempenho ideal. +--- + +Este artigo discute as melhores práticas de desempenho e confiabilidade para aplicativos Expresso aplicados à produção. + +Este tema cai claramente no mundo "devops", abrangendo tanto o desenvolvimento tradicional como as operações. Assim, a informação é dividida em duas partes: + +- Coisas a fazer no seu código (a parte de desenvolvedor): + - [Usar compressão gzip](#use-gzip-compression) + - [Não usar funções síncronas](#dont-use-synchronous-functions) + - [Faça o registro corretamente](#do-logging-correctly) + - [Tratar exceções corretamente](#handle-exceptions-properly) +- Coisas a fazer em seu ambiente / configuração (a parte ops): + - [Definir NODE_ENV para "produção"](#set-node_env-to-production) + - [Verifique se seu aplicativo reinicia automaticamente](#ensure-your-app-automatically-restarts) + - [Execute seu aplicativo em um cluster](#run-your-app-in-a-cluster) + - [Resultados da requisição de cache](#cache-request-results) + - [Usar um balanceador de carga](#use-a-load-balancer) + - [Usar um proxy reverso](#use-a-reverse-proxy) + +## Coisas a fazer em seu código + +Aqui estão algumas coisas que você pode fazer em seu código para melhorar o desempenho do seu aplicativo: + +- [Usar compressão gzip](#use-gzip-compression) +- [Não usar funções síncronas](#dont-use-synchronous-functions) +- [Faça o registro corretamente](#do-logging-correctly) +- [Tratar exceções corretamente](#handle-exceptions-properly) + +### Usar compressão gzip + +O compactação Gzip pode diminuir significativamente o tamanho do corpo da resposta e, assim, aumentar a velocidade de um aplicativo da web. Use o [compression](https://www.npmjs.com/package/compression) middleware para compressão gzip no seu aplicativo Express. Por exemplo: + +```js +const compression = require('compression'); +const express = require('express'); +const app = express(); + +app.use(compression()); +``` + +Para um sítio web de alto tráfego, em produção, a melhor maneira de colocar a compressão no lugar é implementá-la a um nível de proxy reverso (veja [usar um proxy reverso](#use-a-reverse-proxy)). Nesse caso, não é necessário utilizar um middleware de compressão. Para detalhes sobre como ativar a compressão gzip no Nginx, consulte [Module ngx_http_gzip_module](http://nginx.org/en/docs/http/ngx_http_gzip_module) na documentação do Nginx. + +### Não usar funções síncronas + +Os métodos e funções síncríveis ligam o processo de execução até que retornam. Uma única chamada para uma função síncrona pode retornar em alguns microsegundos ou milissegundos, No entanto, em sites com alto tráfego, essas chamadas somam e reduzem o desempenho do aplicativo. Evite a sua utilização em produção. + +Embora o Node e muitos módulos fornecem versões sincronizadas e assíncronas de suas funções, sempre use a versão assíncrona em produção. O único momento em que uma função síncrona pode ser justificada é na inicialização inicial. + +Você pode usar o sinalizador de linha de comando `--trace-sync-io` para imprimir um aviso e um rastreamento de pilha sempre que seu aplicativo usar uma API síncrona. Claro, você não gostaria de usar isto em produção, mas sim de garantir que seu código esteja pronto para produção. Veja a [documentação de opções de linha de comando do nó](https://nodejs.org/api/cli#cli_trace_sync_io) para mais informações. + +### Faça o login corretamente + +Em geral, existem duas razões para registrar seu aplicativo: para depuração e para registrar a atividade do aplicativo (essencialmente, tudo o mais). Usar `console.log()` ou `console.error()` para imprimir mensagens de log no terminal é uma prática comum de desenvolvimento. Mas [essas funções são sincronizadas](https://nodejs.org/api/console#console) quando o destino é um terminal ou um arquivo, então eles não são adequados para produção, a menos que você canalize a saída para outro programa. + +#### Para depuração + +Se você está logando para fins de depuração, em vez de usar `console.log()`, use um módulo de depuração especial, como [debug](https://www.npmjs.com/package/debug). Esse módulo permite que você use a variável de ambiente DEBUG para controlar quais mensagens de depuração são enviadas para `console.error()`, se houver. Para manter seu aplicativo puramente assíncrono, você ainda pode usar o comando `console.error()` para outro programa. Mas então, você realmente não vai depurar na produção, não é? + +#### Para atividades do aplicativo + +Se você está registrando a atividade do aplicativo (por exemplo, monitorando tráfego ou chamadas de API), em vez de usar o `console. og()`, use uma biblioteca de logs como [Pino](https://www.npmjs.com/package/pino), que é a opção mais rápida e eficiente disponível. + +### Manipular exceções corretamente + +Aplicativos do nó falham quando encontram uma exceção desmarcada. Não lidar com exceções e tomar as ações adequadas fará com que seu app Express pare de funcionar e fique offline. Se você seguir o conselho em [Verifique se seu aplicativo reinicia automaticamente](#ensure-your-app-automatically-restarts) abaixo, então seu aplicativo se recuperará de uma falha. Felizmente, os aplicativos Express normalmente têm um curto tempo de inicialização. No entanto, o senhor deputado quer evitar a queda, e, para isso, tem de tratar devidamente as excepções. + +Para garantir que você lida com todas as exceções, use as seguintes técnicas: + +- [Usar captura final](#use-try-catch) +- [Usar promessas](#use-promises) + +Antes de mergulhar nestes tópicos, você deve ter um entendimento básico da manipulação de erro Node/Express: usar callback error first e propagar erros no middleware. O nó utiliza uma convenção "error-first callback" para retornar erros de funções assíncronas, onde o primeiro parâmetro para a função de callback é o objeto de erro, seguido pelos dados de resultado em parâmetros de sucesso. Para indicar nenhum erro, passe nulo como primeiro parâmetro. A função de callback deve seguir correspondentemente a convenção de callback error-first para lidar de forma significativa com o erro. E em Express, a melhor prática é usar a função next() para propagar erros através da cadeia de middleware. + +Para saber mais sobre os fundamentos da manipulação de erros, veja: + +- [Erro manipulando o Node.js](https://www.tritondatacenter.com/node-js/production/design/errors) + +#### Usar try-catch + +Try-catch é uma construção de idioma JavaScript que você pode usar para capturar exceções em código síncrono. Use a tentativa de captura, por exemplo, para lidar com erros de análise JSON, como mostrado abaixo. + +Aqui está um exemplo de utilização de capturas de tentativa para lidar com uma potencial exceção do crash do processo. +Esta função middleware aceita um parâmetro de campo de consulta chamado "params" que é um objeto JSON. + +```js +app.get('/search', (req, res) => { + // Simulating async operation + setImmediate(() => { + const jsonStr = req.query.params; + try { + const jsonObj = JSON.parse(jsonStr); + res.send('Success'); + } catch (e) { + res.status(400).send('Invalid JSON string'); + } + }); +}); +``` + +No entanto, a tentativa y-catch só funciona para código síncrono. Porque a plataforma Node é principalmente assíncrona (particularmente em ambiente de produção), a tentativa de captura não vai pegar muitas exceções. + +#### Usar promessas + +Quando um erro é lançado em uma função `async` ou uma promessa rejeitada é aguardada dentro de uma função `async`, esses erros serão passados para o manipulador de erros como se chamando `next(err)` + +```js +app.get('/', async (req, res, next) => { + const data = await userData(); // If this promise fails, it will automatically call `next(err)` to handle the error. + + res.send(data); +}); + +app.use((err, req, res, next) => { + res.status(err.status ?? 500).send({ error: err.message }); +}); +``` + +Além disso, você pode usar funções assíncronas para o seu middleware, e o roteador irá lidar com erros se a promessa falhar, por exemplo: + +```js +app.use(async (req, res, next) => { + req.locals.user = await getUser(req); + + next(); // This will be called if the promise does not throw an error. +}); +``` + +A melhor prática é lidar com os erros o mais próximo possível do site. Então enquanto isso é manipulado no roteador, É melhor encontrar o erro no middleware e lidar com ele sem depender de um middleware separado para manipular erros. + +#### O que não fazer + +Uma coisa que você não deveria fazer é ouvir o evento `uncaughtException`, emitido quando uma exceção bolha até o laço de repetição do evento. Adicionando um listener de eventos para `uncaughtException` mudará o comportamento padrão do processo que está encontrando uma exceção; o processo continuará a decorrer apesar da excepção. Isso pode soar como uma boa maneira de impedir que seu aplicativo caia, mas continuar a executar o aplicativo após uma exceção não detectada é uma prática perigosa e não é recomendado, porque o estado do processo se torna pouco fiável e imprevisível. + +Além disso, usar `uncaughtException` é oficialmente reconhecido como [crude](https://nodejs.org/api/process#process_event_uncaughtexception). Então ouvir por `uncaughtException` é apenas uma má ideia. É por isso que recomendamos coisas como processos múltiplos e supervisores: falhar e reiniciar é muitas vezes a maneira mais confiável de recuperar de um erro. + +Também não recomendamos o uso de [domains](https://nodejs.org/api/domain). Geralmente isso não resolve o problema e é um módulo obsoleto. + +## Coisas a fazer no seu ambiente / configuração + +Aqui estão algumas coisas que você pode fazer em seu ambiente de sistema para melhorar o desempenho do seu aplicativo: + +- [Definir NODE_ENV para "produção"](#set-node_env-to-production) +- [Verifique se seu aplicativo reinicia automaticamente](#ensure-your-app-automatically-restarts) +- [Execute seu aplicativo em um cluster](#run-your-app-in-a-cluster) +- [Resultados da requisição de cache](#cache-request-results) +- [Usar um balanceador de carga](#use-a-load-balancer) +- [Usar um proxy reverso](#use-a-reverse-proxy) + +### Definir NODE_ENV para "produção" + +A variável de ambiente NODE_ENV especifica o ambiente em que uma aplicação está sendo executada (usualmente, desenvolvimento ou produção). Uma das coisas mais simples que você pode fazer para melhorar o desempenho é configurar NODE_ENV para `produção`. + +Definir NODE_ENV para "produção" faz Expressão: + +- Modelos de exibição em cache. +- Arquivos CSS do cache gerados a partir de extensões CSS. +- Gerar mensagens de erro menos detalhadas. + +[Testes indicados](https://www.dynatrace.com/news/blog/the-drastic-effects-of-omitting-node-env-in-your-express-js-applications/) que apenas fazer isso pode melhorar o desempenho do aplicativo por um fator de três! + +Se você precisar escrever código de ambiente específico, você pode verificar o valor de NODE_ENV com `process.env.NODE_ENV`. Esteja ciente de que verificar o valor de qualquer variável de ambiente implica uma penalização de desempenho, assim como deve ser feito com moderação. + +No desenvolvimento, você normalmente define variáveis de ambiente em seu shell interativo, por exemplo, usando `export` ou seu arquivo `.bash_profile`. Mas, em geral, você não deve fazer isso em um servidor de produção; em vez disso, use o sistema init do seu SO (sistema). A próxima seção fornece mais detalhes sobre o uso do seu sistema de init em geral mas a configuração de `NODE_ENV` é tão importante para desempenho (e fácil de fazer), que é destacada aqui. + +Com o sistema, use a diretiva `Ambiente` no seu arquivo unitário. Por exemplo: + +```sh + +Environment=NODE_ENV=production +``` + +Para obter mais informações, consulte [Usando Variáveis de Ambiente em Unidades sistêmicas](https://www.flatcar.org/docs/latest/setup/systemd/environment-variables/). + +### Certifique-se de que seu aplicativo reinicie automaticamente + +Em produção, você não quer que sua aplicação fique offline, nunca. Isto significa que você precisa ter certeza que ele reiniciará tanto se o aplicativo falhar e o próprio servidor falhar. Embora você espere que nenhum desses acontecimentos ocorra, realisticamente você deve ter em conta ambas as eventualidades por: + +- Usando um gerenciador de processo para reiniciar o aplicativo (e Node) quando ele travar. +- Usando o sistema de init fornecido pelo seu sistema operacional para reiniciar o gerenciador de processos quando o sistema operacional travar. Também é possível usar o sistema sem um gerente de processo. + +Aplicativos do nó falham se encontrarem uma exceção não capturada. A principal coisa que você precisa fazer é garantir que seu aplicativo seja bem testado e tenha todas as exceções (veja [handle exceptions correctly](#handle-exceptions-properly) para detalhes). Mas como falha, coloque um mecanismo em prática para garantir que se e quando o aplicativo parar de funcionar, ele será reiniciado automaticamente. + +#### Usar um gerenciador de processo + +Em desenvolvimento, você iniciou seu aplicativo simplesmente pela linha de comando com `node server.js` ou algo parecido. Mas fazer isto em produção é uma receita para o desastre. Se o aplicativo falhar, ele ficará offline até você reiniciá-lo. Para garantir que seu aplicativo seja reiniciado se ele falhar, use um gerenciador de processo. Um gerenciador de processo é um "container" para aplicativos que facilitam a implantação, fornece alta disponibilidade, e permite que você gerencie o aplicativo em tempo de execução. + +Além de reiniciar seu aplicativo quando ele falhar, um gerente de processo pode habilitá-lo: + +- Receba informações sobre o desempenho da execução e o consumo de recursos. +- Modifique as configurações dinamicamente para melhorar o desempenho. +- Controle agrupamento (pm2). + +Historicamente, foi popular usar um gerente de processo Node.js como [PM2](https://github.com/Unitech/pm2). Veja a documentação deles, se você quiser fazer isso. No entanto, recomendamos a utilização de seu sistema de init para gerenciamento de processos. + +#### Usar um sistema de entrada + +A próxima camada de confiabilidade é garantir que seu aplicativo seja reiniciado quando o servidor reiniciar. Os sistemas ainda podem descer por diversas razões. Para garantir que seu aplicativo seja reiniciado se o servidor falhar, use o sistema incorporado no seu sistema operacional. O sistema principal de init em uso hoje é [systemd](https://wiki.debian.org/systemd). + +Existem duas maneiras de usar sistemas de entrada com seu aplicativo Express: + +- Execute seu aplicativo em um gerenciador de processo e instale o gerente de processo como um serviço com o sistema de init. O gerenciador de processos irá reiniciar seu aplicativo quando o aplicativo falhar, e o sistema inicial irá reiniciar o gerenciador de processos quando o sistema operacional for reiniciado. Esta é a abordagem recomendada. +- Execute seu aplicativo (e Node) diretamente com o sistema init. Isto é um pouco mais simples, mas você não obtém as vantagens adicionais de usar um gerenciador de processo. + +##### Systemd + +O Systemd é um gerenciador de serviços e sistema Linux. A maioria das principais distribuições de Linux adotaram o sistema como sistema de init padrão. + +Um arquivo de configuração de serviço systemd é chamado de _unit file_, com um nome de arquivo terminando em `.service`. Aqui está um exemplo de arquivo unitário para gerenciar um aplicativo Node diretamente. Substitua os valores colocados em \`para o seu sistema e aplicativo: + +```sh +[Unit] +Description= + +[Service] +Type=simple +ExecStart=/usr/local/bin/node +WorkingDirectory= + +User=nobody +Group=nogroup + + +Environment=NODE_ENV=production + + +LimitNOFILE=infinity + + +LimitCORE=infinity + +StandardInput=null +StandardOutput=syslog +StandardError=syslog +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +Para obter mais informações sobre o sistema, consulte a [referência do sistema (man page)](http://www.freedesktop.org/software/systemd/man/systemd.unit). + +### Executar seu aplicativo em um cluster + +Em um sistema multi-núcleo, você pode aumentar o desempenho de um aplicativo Node muitas vezes, iniciando um cluster de processos. Um cluster executa várias instâncias do aplicativo, idealmente uma instância em cada núcleo da CPU, distribuindo assim a carga e tarefas entre as instâncias. + +![Balanceamento entre instâncias de aplicação usando a API de agrupamento](/images/clustering.png) + +IMPORTANTE: Como as instâncias do aplicativo são executadas como processos separados, eles não compartilham o mesmo espaço de memória. Ou seja, objetos são locais para cada instância do aplicativo. Por conseguinte, não pode manter o estado no código de candidatura. No entanto, você pode usar um datastore na memória como [Redis](http://redis.io/) para armazenar dados e estado relacionados à sessão. Esta ressalva se aplica essencialmente a todas as formas de escala horizontal, seja agrupamento com vários processos ou vários servidores físicos. + +Em apps agrupados, os processos dos trabalhadores podem falhar individualmente sem afetar o resto dos processos. Além das vantagens de desempenho, isolamento de falhas é outra razão para executar um agrupamento de processos de aplicativos. Sempre que um processo do worker parar de funcionar, tenha certeza de registrar o evento e gerar um novo processo usando cluster.fork(). + +#### Usando módulo de cluster do Node + +É possível agrupar com o [módulo cluster do Node](https://nodejs.org/api/cluster). Isto permite a um processo mestre gerar processos de trabalhadores e distribuir conexões de entrada entre os trabalhadores. + +#### Usando PM2 + +Se você publicar sua aplicação com PM2, então você pode aproveitar o clustering _without_ para modificar o código da sua aplicação. Você deve garantir sua [inscrição sem estado](https://pm2.keymetrics.io/docs/usage/specifics/#stateless-apps) primeiro, significando que nenhum dado local é armazenado no processo (como sessões, conexões de websocket e coisas parecidas). + +Ao executar um aplicativo com PM2, você pode habilitar o **modo de agrupamento** para executá-lo em um cluster com várias instâncias de sua escolha, como o número de CPUs disponíveis na máquina. Você pode alterar manualmente o número de processos no cluster usando a ferramenta de linha de comando `pm2` sem parar o aplicativo. + +Para ativar o modo de agrupamento, inicie seu aplicativo assim: + +```bash + +$ pm2 start npm --name my-app -i 4 -- start + +$ pm2 start npm --name my-app -i max -- start +``` + +Isto também pode ser configurado em um arquivo de processo PM2 (`ecosystem.config. s` ou similar) definindo `exec_mode` para `cluster` e `instâncias` para o número de trabalhadores para começar. + +Ao executar, o aplicativo pode ser dimensionado assim: + +```bash + +$ pm2 scale my-app +3 + +$ pm2 scale my-app 2 +``` + +Para obter mais informações sobre agrupamento com PM2, consulte [Modo Cluster](https://pm2.keymetrics.io/docs/usage/cluster-mode/) na documentação PM2. + +### Resultados da requisição em cache + +Outra estratégia para melhorar o desempenho em produção é armazenar em cache o resultado das solicitações, para que seu aplicativo não repita a operação para atender o mesmo pedido repetidamente. + +Use um servidor de cache como [Varnish](https://www.varnish-cache.org/) ou [Nginx](https://blog.nginx.org/blog/nginx-caching-guide) (veja também [Nginx Caching](https://serversforhackers.com/nginx-caching/)) para melhorar muito a velocidade e o desempenho de sua aplicação. + +### Use um balanceador de carga + +Não importa o quão otimizado um app seja, uma única instância pode manipular apenas uma quantidade limitada de carga e tráfego. Uma maneira de expandir um aplicativo é rodando várias instâncias dele e distribuindo o tráfego através de um balanceador de carga. Configurar um balanceador de carga pode melhorar o desempenho e a velocidade do seu aplicativo, e habilitá-lo a escalar mais do que é possível com uma única instância. + +Um balanceador de carga geralmente é um proxy reverso que orqualiza o tráfego de e para a partir de várias instâncias de aplicativos e servidores. Você pode facilmente configurar um balanceador de carga para o seu aplicativo usando [Nginx](https://nginx.org/en/docs/http/load_balancing) ou [HAProxy](https://www.digitalocean.com/community/tutorials/an-introduction-to-haproxy-and-load-balancing-concepts). + +Com o balanceamento de carga, você pode ter que garantir que os pedidos que estão associados a um determinado ID de sessão estejam conectados ao processo que os originou. Isto é conhecido como afinidade de sessão, ou _sessões fixas_, e pode ser abordado pela sugestão acima para usar um armazenamento de dados, como Redis para dados de sessão (dependendo do seu aplicativo). Para uma discussão, consulte [Usando múltiplos nós](https://socket.io/docs/v4/using-multiple-nodes/). + +### Usar um proxy reverso + +Um proxy reverso está na frente de um aplicativo web e executa operações de suporte sobre as solicitações, além de direcionar solicitações para o aplicativo. Ele pode lidar com páginas de erro, compressão, cache, arquivos de servidor, e o equilíbrio de carga entre outras coisas. + +Atingir tarefas que não exigem conhecimento do estado do aplicativo para um proxy reverso libera o Express para executar tarefas de aplicativo especializado. Por este motivo, é recomendado executar Expresso atrás de um proxy reverso como [Nginx](https://www.nginx.org/) ou [HAProxy](https://www.haproxy.org/) em produção. diff --git a/src/content/pages/pt-br/advanced/best-practice-security.mdx b/src/content/pages/pt-br/advanced/best-practice-security.mdx new file mode 100644 index 0000000000..b045b74220 --- /dev/null +++ b/src/content/pages/pt-br/advanced/best-practice-security.mdx @@ -0,0 +1,276 @@ +--- +title: "Melhores Práticas de Produção: Segurança" +description: Descubra as melhores práticas de segurança cruciais para aplicativos Express em produção, incluindo o uso de TLS, validação de entrada, cookies seguros e prevenção de vulnerabilidades. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +O termo *"produção"* se refere ao estágio no ciclo de vida do software quando uma aplicação ou API está geralmente disponível para seus usuários finais ou consumidores. Em contraste, na etapa "development"__ , você ainda está escrevendo e testando o código, e o aplicativo não está aberto para acesso externo. Os ambientes de sistema correspondentes são conhecidos como ambientes de *produção* e *desenvolvimento*, respectivamente. + +Os ambientes de desenvolvimento e de produção são concebidos de forma diferente e têm requisitos muito diferentes. O que há de bom no desenvolvimento pode não ser aceitável na produção. Por exemplo, em um ambiente de desenvolvimento, você pode querer um registro detalhado de erros para depuração, enquanto o mesmo comportamento pode se tornar uma preocupação de segurança em ambiente de produção. E no desenvolvimento, você não precisa se preocupar com escalabilidade, confiabilidade e desempenho, enquanto esses problemas se tornam críticos em produção. + + + +Se acredita que descobriu uma vulnerabilidade de segurança em Express, consulte Segurança +Políticas e Procedimentos. + + + +As melhores práticas de segurança para aplicações Expressas na produção incluem: + +* [Práticas de Melhor Produção: Segurança](#production-best-practices-security) + * [Overview](#overview) + * [Não usar versões descontinuadas ou vulneráveis do Express](#dont-use-deprecated-or-vulnerable-versions-of-express) + * [Usar TLS](#use-tls) + * [Não confie na entrada do usuário](#do-not-trust-user-input) + * [Impedir redirecionamentos abertos](#prevent-open-redirects) + * [Usar capacete](#use-helmet) + * [Reduzir impressão digital](#reduce-fingerprinting) + * [Usar cookies de forma segura](#use-cookies-securely) + * [Não usar o nome padrão de cookie da sessão](#dont-use-the-default-session-cookie-name) + * [Definir opções de segurança de cookies](#set-cookie-security-options) + * [Impedir ataques brute-force contra a autorização](#prevent-brute-force-attacks-against-authorization) + * [Garanta que suas dependências sejam seguras](#ensure-your-dependencies-are-secure) + * [Evitar outras vulnerabilidades conhecidas](#avoid-other-known-vulnerabilities) + * [Considerações adicionais](#additional-considerations) + +## Não usar versões obsoletas ou vulneráveis do Express + +Expresso 2,x e 3.x já não são mantidos. Problemas de segurança e desempenho nestas versões não serão corrigidos. Não os utilize! Se você não se moveu para a versão 4, siga o [guia de migração](/en/guide/migrating-4) ou considere [Opções de Suporte Comercial](/en/support#commercial-support-options). + +Certifique-se também de que você não está usando nenhuma das versões vulneráveis Express listadas na [Página de atualizações de segurança](/en/advanced/security-updates). Se você estiver, atualize para uma das versões estáveis, de preferência a mais recente. + +## Usar TLS + +Se seu aplicativo lida com ou transmite dados confidenciais, use [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) para proteger a conexão e os dados. Esta tecnologia criptografa dados antes de ser enviada do cliente para o servidor, impedindo assim alguns hackers comuns (e fáceis). Embora solicitações do Ajax e POST não sejam óbvias e pareçam "ocultas" nos navegadores, seu tráfego de rede está vulnerável ao [sniffing de pacotes](https://en.wikipedia.org/wiki/Packet_analyzer) e [ataques do meio](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). + +Você deve estar familiarizado com a criptografia Secure Socket Layer (SSL). [TLS é simplesmente a próxima progressão do SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). Em outras palavras, se você estava usando SSL antes, considere atualizar para o TLS. Em geral, recomendamos o Nginx para lidar com TLS. Para uma boa referência para configurar TLS no Nginx (e outros servidores), consulte [Configurações de servidores recomendadas (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). + +Além disso, uma ferramenta prática para obter um certificado TLS gratuito é [Let's Encrypt](https://letsencrypt.org/about/), uma ferramenta gratuita, automatizada, e abrir autoridade certificadora (CA) fornecida pelo [Grupo de Investigação de Segurança da Internet (ISRG)](https://www.abetterinternet.org/). + +## Não confiar em entrada do usuário + +Para aplicativos web, um dos requisitos de segurança mais críticos é a validação e tratamento adequado dos dados de entrada do usuário. Isto tem muitas formas e não as cobriremos todas aqui. +Em última análise, a responsabilidade de validar e manipular corretamente os tipos de entrada de usuário que seu aplicativo aceita é sua. + +### Impedir redirecionamentos abertos + +Um exemplo de entrada de usuário potencialmente perigosa é um *open redirect*, onde um aplicativo aceita uma URL como entrada de usuário (muitas vezes na consulta de URL, por exemplo `? rl=https://exemplo. om`) e usa `res.redirect` para definir o cabeçalho `location` e +return um status de 3xx. + +Uma aplicação deve validar que suporta redirecionamento para a URL de entrada, para evitar enviar usuários para links maliciosos, como sites de phishing, entre outros riscos. + +Aqui está um exemplo de verificar URLs antes de usar `res.redirect` ou `res.location`: + +```js +app.use((req, res) => { + tente { + if (nova Url(req. uery.url).host !== 'example.com') { + return res.status(400). nd(`Redirecionamento não suportado para host: ${req.query.url}`); + } + } capturar (e) { + retorna! tatus(400).end(`url inválida: ${req.query.url}`); + } + res.redirect(req.query.url); +}); +``` + +## Usar o Capacete + +[Helmet][helmet] pode ajudar a proteger seu app de algumas vulnerabilidades conhecidas da web, definindo os cabeçalhos HTTP adequadamente. + +Capacete é uma função middleware que define cabeçalhos de resposta HTTP relacionados à segurança. Capacete define os seguintes cabeçalhos por padrão: + +* `Content-Security-Policy`: Uma poderosa lista de permissões do que pode acontecer na sua página, que mitiga muitos ataques +* `Cross-Origin-Opener-Policy`: Ajuda a isolar sua página +* `Cross-Origin-Resource-Policy`: Bloqueia outros de carregar seus recursos de cruzamento de origem +* `Origin-Agent-Cluster`: Altera o isolamento de processo para ser baseado na origem +* `Referrer-Policy`: Controla o cabeçalho [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) +* `Strict-Transport-Security`: Diz aos navegadores para preferirem HTTPS +* `X-Content-Type-Options`: Evitar [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +* `X-DNS-Prefetch-Control`: Controls DNS prefetching +* `X-Download-Options`: Força os downloads a serem salvos (apenas no Internet Explorer +* `X-Frame-Options`: Cabeçalho de legado que mitiga [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) ataques +* `X-Perting-Cross-Domain-Policies`: Controla o comportamento entre domínios para produtos Adobe, como a Acrobat +* `X-Powered-By`: Informações sobre o servidor web. Removido porque poderia ser utilizado em ataques simples +* `X-XSS-Protection`: Cabeçalho de legado que tenta mitigar [ataques XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), mas piora as coisas, então o Capacete desabilita + +Cada cabeçalho pode ser configurado ou desativado. Para ler mais sobre isso, por favor, vá para [a documentação do site][helmet]. + +Instalar o Capacete como qualquer outro módulo: + +```bash +$ npm install helmet +``` + +Então para usá-lo em seu código: + +```js +// ... + +const helmet = require('helmet'); +app.use(helmet()); + +// ... +``` + +## Reduzir impressão digital + +Ele pode ajudar a fornecer uma camada extra de segurança para reduzir a capacidade dos invasores de determinar +o software que um servidor utiliza, conhecido como "impressão digital". Embora não seja um problema de segurança em si, +reduzir a capacidade de impressão digital de um aplicativo melhora sua posição geral de segurança. +O software do servidor pode ser impresso por peculiares em como ele responde a solicitações específicas, por exemplo em +os cabeçalhos de resposta HTTP. + +Por padrão, o Expresso envia o cabeçalho de resposta `X-Powered-By` que você pode +desabilitar usando o método `app.disable()`: + +```js +app.disable('x-powered-por'); +``` + + + +Desativar o cabeçalho 'X-Powered-By ' não impede que um invasor sofisticado determine +que um aplicativo está executando o Express. Isso pode desencorajar um exploit casual, mas existem outras maneiras de +determinar que um aplicativo está executando o Expresso. + + + +Express também envia suas próprias mensagens formatadas "404 Não Encontradas" e erro de formatação +mensagens de resposta. Elas podem ser alteradas por +[adicionando seu próprio manipulador não encontrado](/en/starter/faq#how-do-i-handle-404-responses) +e +[escrevendo seu próprio manipulador de erro](/en/guide/error-handling#writing-error-handlers): + +```js +// last app.use calls right before app.listen(): + +// personalizado 404 +app.use((req, res, next) => { + res.status(404). end("Desculpe não consegue encontrar isso!"); +}); + +// aplicativo personalizado para manipulador de erros +. se((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Algo quebra!'); +}); +``` + +## Usar cookies de forma segura + +Para garantir que cookies não abram seu aplicativo para exploits, não use o nome padrão de cookie de sessão e defina as opções de segurança de cookie adequadamente. + +Existem dois principais módulos de sessão do cookie middleware: + +* [express-session](https://www.npmjs.com/package/express-session) que substitui `express.session` middleware integrado ao Express 3.x. +* [cookie-session](https://www.npmjs.com/package/cookie-session) that replaces `express.cookieSession` middleware built-in to Express 3.x. + +A principal diferença entre estes dois módulos é como eles salvam os dados da sessão de cookie. O [express-session](https://www.npmjs.com/package/express-session) middleware armazena os dados de sessão no servidor; apenas salva o ID da sessão no próprio cookie, não nos dados da sessão. Por padrão, ele usa armazenamento de memória e não é projetado para um ambiente de produção. Na produção, você precisará configurar uma loja de sessão escalável; ver a lista de [lojas de sessões compatíveis](https://github.com/expressjs/session#compatible-session-stores). + +Em contraste, [cookie-session](https://www.npmjs.com/package/cookie-session) middleware implementa o armazenamento apoiado por cookie: serializa toda a sessão para o cookie, em vez de apenas uma chave de sessão. Use isso apenas quando os dados da sessão são relativamente pequenos e facilmente codificados como valores primitivos (em vez de objetos). Embora os navegadores devem suportar pelo menos 4096 bytes por cookie, para garantir que você não exceda o limite, não exceda um tamanho de 4093 bytes por domínio. Além disso, esteja ciente de que os dados de cookie serão visíveis para o cliente, portanto, se houver qualquer razão para mantê-lo seguro ou obscurecer, então `express-session` pode ser uma melhor escolha. + +### Não usar o nome padrão de cookie de sessão + +Usar o nome padrão de cookie de sessão pode abrir seu aplicativo para ataques. A questão de segurança colocada é semelhante ao `X-Powered-By`: um potencial atacante pode usá-lo para impressão digital do servidor e ataques alvo de acordo. + +Para evitar este problema, use nomes genéricos de cookie, por exemplo, usando [express-session](https://www.npmjs.com/package/express-session) middleware: + +```js +const session = require('express-session'); +app.set('trust proxy', 1); // confia no primeiro proxy +app. se( + session({ + secret: 's3Cur3', + name: 'sessionId', + }) + +``` + +### Definir opções de segurança do cookie + +Defina as seguintes opções de cookies para aumentar a segurança: + +* `secure` - Garante que o navegador envie apenas o cookie via HTTPS. +* `httpOnly` - Garante que o cookie é enviado somente via HTTP(S), não do cliente JavaScript, ajudando a proteger contra ataques de script via site. +* `domínio` - indica o domínio do cookie; use-o para comparar com o domínio do servidor no qual a URL está sendo solicitada. Se eles coincidirem, verifique o atributo de caminho em seguida. +* `path` - indica o caminho do cookie; use-o para comparar com o caminho do pedido. Se este e o domínio corresponderem então envie o cookie na solicitação. +* `expires` - use para definir a data de validade para cookies persistentes. + +Aqui está um exemplo usando [cookie-session](https://www.npmjs.com/package/cookie-session) middleware: + +```js +const session = require('cookie-session'); +const express = require('express'); +const app = express(); + +const expiryDate = new Date(Date. ow() + 60 * 60 * 1000); aplicativo // 1 hora +se( + sessão({ + nome: 'sessão', + chaves: ['chave1', 'chave2'], + cookie: { + seguro: verdadeiro, + httpOnly: true, + domínio: 'exemplo. om', + caminho: 'foo/bar', + expira: data de expiração, + }, + }) +); +``` + +## Evite ataques brutos contra autorização + +Certifique-se de que os endpoints de login estejam protegidos para tornar os dados privados mais seguros. + +Uma técnica simples e poderosa é bloquear tentativas de autorização usando duas métricas: + +1. O número de tentativas consecutivas com o mesmo nome de usuário e endereço IP. +2. O número de tentativas falhadas de um endereço IP por um longo período de tempo. Por exemplo, bloqueie um endereço IP se fizer 100 tentativas falhadas em um dia. + +[rate-limiter-flexible](https://github.com/animir/node-rate-limiter-flexible) pacote fornece ferramentas para tornar essa técnica fácil e rápida. Você pode encontrar [um exemplo de proteção brute-force na documentação](https://github.com/animir/node-rate-limiter-flexible/wiki/Overall-example#login-endpoint-protection) + +## Certifique-se de que suas dependências estejam seguras + +Usar o npm para gerenciar as dependências do seu aplicativo é poderoso e conveniente. Mas os pacotes que você usa podem conter vulnerabilidades de segurança críticas que também podem afetar sua aplicação. A segurança do seu aplicativo só é forte como o link "mais fraco" em suas dependências. + +Desde npm@6, npm revisa automaticamente toda requisição de instalação. Além disso, você pode usar o `npm audit` para analisar sua árvore de dependências. + +```bash +$ auditoria do npm +``` + +Se você deseja ficar mais seguro, considere [Snyk](https://snyk.io/). + +Snyk oferece tanto uma [ferramenta de linha de comando](https://www.npmjs.com/package/snyk) quanto uma [integração com um Github](https://snyk.io/docs/github) que verifica a sua aplicação no [banco de dados de vulnerabilidades de fonte aberta do Snyk](https://snyk.io/vuln/) para quaisquer vulnerabilidades conhecidas em suas dependências. Instalar CLI da seguinte forma: + +```bash +$ npm install -g snyk +$ cd your-app +``` + +Use este comando para testar suas vulnerabilidades: + +```bash +$ teste snyk +``` + +### Evitar outras vulnerabilidades conhecidas + +Fique de olho nos conselhos [Node Security Project](https://npmjs.com/advisories) ou [Snyk](https://snyk.io/vuln/) que possam afetar os módulos Express ou outros que seu aplicativo usa. Em geral, estas bases de dados são excelentes recursos para o conhecimento e ferramentas sobre a segurança dos Nós. + +Finalmente, Aplicativos Expressos—como qualquer outro aplicativo da web—podem ser vulneráveis a uma variedade de ataques baseados na web. Familiarize-se com as conhecidas [vulnerabilidades da web](https://www.owasp.org/www-project-top-ten/) e tome precauções para evitá-las. + +## Considerações adicionais + +Aqui estão mais algumas recomendações do excelente [Checklist de Segurança do Node.js](https://blog.risingstack.com/node-js-security-checklist/). Consulte este post para todos os detalhes destas recomendações: + +* Sempre filtre e sanize a entrada do usuário para proteger contra scripts entre sites (XSS) e ataques de injeção de comando. +* Defenda-se contra ataques de injeção de SQL usando consultas parametrizadas ou declarações preparadas. +* Use a ferramenta de código aberto [sqlmap](http://sqlmap.org/) para detectar as vulnerabilidades de injeção de SQL em seu aplicativo. +* Usar as ferramentas [nmap](https://nmap.org/) e [sslyze](https://github.com/nabla-c0d3/sslyze) para testar a configuração de suas cifras SSL, chaves e renegociação, bem como a validade de seu certificado. +* Use [safe-regex](https://www.npmjs.com/package/safe-regex) para garantir que suas expressões regulares não são suscetíveis a ataques [negação regular de serviço](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS). + +[helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/pt-br/advanced/healthcheck-graceful-shutdown.md b/src/content/pages/pt-br/advanced/healthcheck-graceful-shutdown.md new file mode 100644 index 0000000000..392c97191a --- /dev/null +++ b/src/content/pages/pt-br/advanced/healthcheck-graceful-shutdown.md @@ -0,0 +1,28 @@ +--- +title: Exame de Saúde e Desligamento Gracioso +description: Aprenda como implementar verificações de saúde e encerramentos graciosos em aplicativos Express, para melhorar a confiabilidade, gerenciar implantações e integrar com balanceadores de carga como Kubernetes. +--- + +## Encerramento Gracioso + +Quando você publica uma nova versão do seu aplicativo, você deve substituir a versão anterior. O gerente de processo que você está utilizando primeiro enviará um sinal SIGTERM ao aplicativo para notificá-lo de que ele será encerrado. Assim que o aplicativo receber este sinal, ele deve parar de aceitar novas solicitações, finalizar todas as solicitações em andamento, limpe os recursos que usou, incluindo conexões de banco de dados e bloqueios de arquivos e depois saia. + +### Exemplo + +```js +const server = app.listen(port); + +process.on('SIGTERM', () => { + debug('SIGTERM signal received: closing HTTP server'); + server.close(() => { + debug('HTTP server closed'); + }); +}); +``` + +## Exercícios de saúde + +Um balanceador de carga usa verificações de saúde para determinar se uma instância do aplicativo é saudável e pode aceitar pedidos. Por exemplo, [Kubernetes tem dois exames de saúde](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/): + +- `liveness`, isso determina quando reiniciar um contêiner. +- `pronto`, que determina quando um recipiente está pronto para começar a aceitar tráfego. Quando um pod não está pronto, é removido dos balanceadores de carga de serviço. diff --git a/src/content/pages/pt-br/advanced/security-updates.mdx b/src/content/pages/pt-br/advanced/security-updates.mdx new file mode 100644 index 0000000000..4920c9022f --- /dev/null +++ b/src/content/pages/pt-br/advanced/security-updates.mdx @@ -0,0 +1,87 @@ +--- +title: Atualizações de segurança +description: Revise as últimas atualizações de segurança e patches do Express.js, incluindo listas detalhadas de vulnerabilidades para diferentes versões para ajudar a manter um aplicativo seguro. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +vulnerabilidades do Node.js afetam diretamente o Express. Portanto, mantenha um relógio no Node.js +vulnerabilidades e certifique-se que está usando a última versão estável +do Node.js. + + + +A lista abaixo enumera as vulnerabilidades Express que foram corrigidas na atualização da versão especificada. + + + +Se acredita que descobriu uma vulnerabilidade de segurança em Express, consulte Segurança +Políticas e Procedimentos. + + + +## 4.x + +* 4.21.2 + * A dependência `path-to-regexp` foi atualizada para o endereço de um [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +* 4.21.1 + * A dependência `cookie` foi atualizada para o endereço [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), isso pode afetar sua aplicação se você usar `res.cookie`. +* 4.20.0 + * Vulnerabilidade XSS corrigida em `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + * A dependência `serve-static` foi atualizada para o endereço [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). + * A dependência `enviar` foi atualizada para o endereço [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + * A dependência `path-to-regexp` foi atualizada para o endereço de um [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + * A dependência `body-parser` foi atualizada para adicionar um [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), isso pode afetar sua aplicação se você tiver uma url ativa de codificação. +* 4.19.0, 4.19.1 + * Corrigido a vulnerabilidade de redirecionamento aberto em `res.location` e `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +* 4.17.3 + * A dependência `qs` foi atualizada para o endereço [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). Isso pode afetar sua aplicação se as seguintes APIs forem usadas: `req.query`, `req.body`, `req.param`. +* 4.16.0 + * A dependência `encaminhado` foi atualizada para o endereço [vulnerability](https://npmjs.com/advisories/527). Isso pode afetar sua aplicação se as seguintes APIs forem usadas: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + * A dependência `mime` foi atualizada para endereçar um [vulnerability](https://npmjs.com/advisories/535), mas esta issue não afeta o Express. + * A dependência `send` foi atualizada para fornecer uma proteção contra uma [Node.js 8.5.0 vulnerabilidade](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). Isso só afeta a execução do Express na versão 8.5.0 específica do Node.js. +* 4.15.5 + * A dependência `debug` foi atualizada para endereçar um [vulnerability](https://snyk.io/vuln/npm:debug:20170905), mas esta issue não afeta o Express. + * A dependência `fresh` foi atualizada para endereço [vulnerability](https://npmjs.com/advisories/526). Isso afetará sua aplicação se as seguintes APIs forem usadas: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendFile`, `res.sendStatus`. +* 4.15.3 + * A dependência `ms` foi atualizada para endereço [vulnerability](https://snyk.io/vuln/npm:ms:20170412). Isso pode afetar sua aplicação se entrada de string não confiável for passada para a opção `maxAge` nas seguintes APIs: `express.static`, `res.sendfile` e `res.sendFile`. +* 4.15.2 + * A dependência `qs` foi atualizada para endereçar um [vulnerability](https://snyk.io/vuln/npm:qs:20170213), mas esta issue não afeta o Express. Atualizar para 4.15.2 é uma boa prática, mas não é necessário para resolver a vulnerabilidade. +* 4.11.1 + * vulnerabilidade de divulgação de caminhos raiz corrigidos em `express.static`, `res.sendfile`, e `res.sendFile` +* 4.10.7 + * Corrigido a vulnerabilidade de redirecionamento aberto em `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 4.8.8 + * Vulnerabilidades de travessia de diretório fixas em `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +* 4.8.4 + * Node.js 0.10 pode vazar `fd`s em certas situações que afetam `express.static` e `res.sendfile`. Solicitações maliciosas podem causar vazamento de `fd`s e eventualmente levar a erros `EMFILE` e servidor sem resposta. +* 4.8.0 + * Matrizes Sparse que possuem índices extremamente altos na cadeia de consulta pode fazer com que o processo fique sem memória e falhe o servidor. + * Objetos de string de consulta extremamente aninhados poderiam fazer com que o processo bloqueasse e tornar o servidor temporariamente não responsivo. + +## 3.x + + +**Expresso 3.x É END-OF-LIFE E NÃO É LONGER MAINTADO** + +Problemas conhecidos e desconhecidos de segurança e desempenho em 3.x não foram abordados desde a última atualização (1 de agosto de 2015). É altamente recomendado usar a versão mais recente do Express. + +Se você não puder atualizar as anteriores 3.x, considere as [Opções de Suporte Comercial](/en/support#commercial-support-options). + + + +* 3.19.1 + * vulnerabilidade de divulgação de caminhos raiz corrigidos em `express.static`, `res.sendfile`, e `res.sendFile` +* 3.19.0 + * Corrigido a vulnerabilidade de redirecionamento aberto em `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 3.16.10 + * Vulnerabilidades de transposição de diretório fixas em `express.static`. +* 3.16.6 + * Node.js 0.10 pode vazar `fd`s em certas situações que afetam `express.static` e `res.sendfile`. Solicitações maliciosas podem causar vazamento de `fd`s e eventualmente levar a erros `EMFILE` e servidor sem resposta. +* 3.16.0 + * Matrizes Sparse que possuem índices extremamente altos em cadeia de consulta pode fazer com que o processo fique sem memória e falhe o servidor. + * Objetos de string de consulta extremamente aninhados poderiam fazer com que o processo bloqueasse e tornar o servidor temporariamente não responsivo. +* 3.3.0 + * A resposta 404 de uma tentativa de substituição de método não suportado era suscetível a ataques de script entre sites. diff --git a/src/content/pages/pt-br/guide/database-integration.mdx b/src/content/pages/pt-br/guide/database-integration.mdx new file mode 100644 index 0000000000..ef5e65beff --- /dev/null +++ b/src/content/pages/pt-br/guide/database-integration.mdx @@ -0,0 +1,503 @@ +--- +title: Integração com base de dados +description: Descubra como integrar vários bancos de dados com aplicações do Express.js, incluindo exemplos de configuração para MongoDB, MySQL, PostgreSQL e muito mais. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Adicionar a capacidade de conectar bancos de dados aos aplicativos Express é apenas uma questão de carregar um driver Node.js apropriado para o banco de dados em seu aplicativo. Este documento explica brevemente como adicionar e usar alguns dos mais populares módulos Node.js para os sistemas de banco de dados no seu aplicativo Express: + +* [Cassandra](#cassandra) +* [Couchbase](#couchbase) +* [CouchDB](#couchdb) +* [LevelDB](#leveldb) +* [MySQL](#mysql) +* [MongoDB](#mongodb) +* [Neo4j](#neo4j) +* [Oracle](#oracle) +* [PostgreSQL](#postgresql) +* [Redis](#redis) +* [SQL Server](#sql-server) +* [SQLite](#sqlite) +* [Elasticsearch](#elasticsearch) + + + +Estes motoristas da base de dados estão entre muitos que estão disponíveis. Para outras opções, pesquise no site +[npm](https://www.npmjs.com/). + + + +## Cassandra + +**Módulo**: [cassandra-driver](https://github.com/datastax/nodejs-driver) + +### Instalação + +```bash +$ npm install cassandra-driver +``` + +### Exemplo + +```js +const cassandra = require('cassandra-driver'); +const client = new cassandra.Client({ contactPoints: ['localhost'] }); + +cliente. xecute('selecione chave de system.local', (err, result) => { + if (err) throw err; + console.log(result.rows[0]); +}); +``` + +## Couchbase + +**Módulo**: [couchnode](https://github.com/couchbase/couchnode) + +### Instalação + +```bash +$ npm install couchbase +``` + +### Exemplo + +```js +const couchbase = require('couchbase'); +const bucket = new couchbase.Cluster('http://localhost:8091').openBucket('bucketName'); + +// adiciona um documento a um balde +. nsert('document-key', { name: 'Matt', shoeSize: 13 }, (err, result) => { + if (err) { + console. og(err); + } else { + console. og(resultado); + } +}); + +// recebe todos os documentos com o tamanho de sapatos 13 +const n1ql = 'SELECT d. DE `bucketName` d WHERE shoeSize = $1'; +const query = N1qlQuery. romString(n1ql); +bucket.query(query, [13], (err, result) => { + if (err) { + console. og(err); + } else { + console.log(resultado); + } +}); +``` + +## CouchDB + +**Módulo**: [nano](https://github.com/dscape/nano) + +### Instalação + +```bash +$ npm install nano +``` + +### Exemplo + +```js +const nano = require('nano')('http://localhost:5984'); +nano.db.create('books'); +const books = nano.db. se('livros'); + +// Insira um documento de livro no banco de dados de livros +livros. nsert({ name: 'A Arte da guerra' }, null, (err, body) => { + if (err) { + console. og(err); + } else { + console. og(corpo); + } +}); + +// Pegue uma lista de todos os livros +livros. ist((err, corpo) => { + if (err) { + console. og(err); + } else { + console.log(body.rows); + } +}); +``` + +## LevelDB + +**Módulo**: [levelup](https://github.com/rvagg/node-levelup) + +### Instalação + +```bash +$ npm install level levelup leveldown +``` + +### Exemplo + +```js +const levelup = require('levelup'); +const db = levelup('./mydb'); + +db. ut('nome', 'NívelUP', (err) => { + if (err) return console.log('Ooops!', err); + + db. et('nome', (err, value) => { + se (err) retornar um console. og('Ooops!', err); + + console.log(`name=${value}`); + }); +}); +``` + +## MySQL + +**Módulo**: [mysql](https://github.com/felixge/node-mysql/) + +### Instalação + +```bash +$ npm install mysql +``` + +### Exemplo + +```js +const mysql = require('mysql'); +const connection = mysql.createConnection({ + host: 'localhost', + user: 'dbuser', + password: 's3kreee7', + database: 'my_db', +}); + +connection.connect(); + +connection.query('SELECT 1 + 1 AS solution', (err, rows, fields) => { + if (err) throw err; + + console.log('The solution is: ', rows[0].solution); +}); + +connection.end(); +``` + +## MongoDB + +**Módulo**: [mongodb](https://github.com/mongodb/node-mongodb-native) + +### Instalação + +```bash +$ npm install mongodb +``` + +### Exemplo (v2.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { + if (err) throw err; + + db. ollection('mammal') + .find() + . oArray((err, result) => { + if (err) throw err; + + console. og(resultado); + }); +}); +``` + +### Exemplo (v3.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, client) => { + if (err) throw err; + + const db = client. b('animais'); + + db.collection('mammals') + .find() + . oArray((err, result) => { + if (err) throw err; + + console. og(resultado); + }); +}); +``` + +Se você quer um driver de objeto para MongoDB, olhe para [Mongoose](https://github.com/LearnBoost/mongoose). + +## Neo4j + +**Módulo**: [neo4j-driver](https://github.com/neo4j/neo4j-javascript-driver) + +### Instalação + +```bash +$ npm install neo4j-driver +``` + +### Exemplo + +```js +const neo4j = require('neo4j-driver'); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth. asic('neo4j', 'letmein')); + +const session = driver.session(); + +session.readTransaction((tx) => { + return tx + . un('MATCH (n) contagem RETURN COMO count') + .then((res) => { + console.log(res.records[0]. et('count')); + }) + .catch((error) => { + console. og(erro); + }); +}); +``` + +## Orátopo + +**Módulo**: [oracledb](https://github.com/oracle/node-oracledb) + +### Instalação + +NOTA: [Ver pré-requisitos de instalação](https://github.com/oracle/node-oracledb#-installation). + +```bash +$ npm install oracledb +``` + +### Exemplo + +```js +const oracledb = require('oracledb'); +const config = { + usuário: '', + password: '', + conectando: 'localhost:1521/orcl', +}; + +função async getEmployee(empId) { + let conn; + + tente { + conn = await oracledb. etConnection(config); + + const result = await conn. xecute('selecione * de funcionários onde empregado_id = :id', [empId]); + + console. og(result.rows[0]); + } captura (err) { + console. og('Ai! , err); + } finalmente { + if (conn) { + // atribuição de conn funcionou, precisa fechar + aguarda conn. Perdido (); + } + } +} + +getEmployee(101); +``` + +## PostgreSQL + +**Módulo**: [pg-promise](https://github.com/vitaly-t/pg-promise) + +### Instalação + +```bash +$ npm install pg-promise +``` + +### Exemplo + +```js +const pgp = require('pg-promise')(/* opções */); +const db = pgp('postgres://username:password@host:port/database'); + +db.one('SELECT $1 AS valor', 123) + . hen((data) => { + console.log('DATA:', data.value); + }) + . atch((error) => { + console.log('ERROR:', error); +}); +``` + +## Redis + +**Módulo**: [redis](https://github.com/mranney/node_redis) + +### Instalação + +```bash +$ npm install redis +``` + +### Exemplo + +```js +const redis = require('redis'); +const client = redis.createClient(); + +client.on('error', (err) => { + console.log(`Error ${err}`); +}); + +cliente. et('string key', 'string val', redis.print); +client.hset('hash key', 'hashtest 1', 'some value', redis.print); +cliente. set(['chave hash', 'hashtest 2', 'alguns outros valor'], redis.print); + +cliente. keys('hash key', (err, respostas) => { + console.log(`${replies.length} respostas:`); + + respostas. orEach((reply, i) => { + console. og(` ${i}: ${reply}`); + }); + + cliente.quit(); +}); +``` + +## Servidor SQL + +**Módulo**: [tedious](https://github.com/tediousjs/tedious) + +### Instalação + +```bash +$ npm install tedious +``` + +### Exemplo + +```js +const Connection = require('tedious').Connection; +const Request = require('tedious'). equipar; + +const config = { + server: 'localhost', + authentication: { + type: 'default', + opções: { + userName: 'nome_seu_usuário', // atualiza-me + senha: 'your_password', // atualiza-me + }, + }, +}; + +const connection = new Connection(config); + +de conexão. n('connect', (err) => { + if (err) { + console. og(err); + } else { + executeStatement(); + } +}); + +função executeStatement() { + request = new Request("selecione 123, 'olá mundo'", (err, rowCount) => { + if (err) { + console. og(err); + } else { + console. og(`${rowCount} linhas`); + } + conexão. lose(); + }); + + request.on('row', (columns) => { + colunas. orEach((column) => { + if (column.value === null) { + console. og('NULL'); + } else { + console.log(coluna. alue); + } + }); + }); + + connection.execSql(request); +} +``` + +## SQLite + +**Módulo**: [sqlite3](https://github.com/mapbox/node-sqlite3) + +### Instalação + +```bash +$ npm install sqlite3 +``` + +### Exemplo + +```js +const sqlite3 = require('sqlite3').verbose(); +const db = new sqlite3.Database(':memory:'); + +db.serialize(() => { + db. un('CRIAR TABLE lorem (info TEXT)'); + const stmt = db. repare('INSERIR VALORES (?)'); + + para (let i = 0; i < 10; i++) { + stmt. un(`Ipsum ${i}`); + } + + stmt.finalize(); + + db. ach('SELECT rowid AS id, info FROM lorem', (err, linha) => { + console. og(`${row.id}: ${row.info}`); + }); +}); + +db.close(); +``` + +## Elasticsearch + +**Módulo**: [elasticsearch](https://github.com/elastic/elasticsearch-js) + +### Instalação + +```bash +$ npm install elasticsearch +``` + +### Exemplo + +```js +const elasticsearch = require('elasticsearch'); +const client = elasticsearch.Client({ + host: 'localhost:9200', +}); + +client + . earch({ + index: 'books', + type: 'book', + corpo: { + query: { + multi_match: { + query: 'express js', + campos: ['title', 'description'], + }, + }, + }, + }) + . hen( + (resposta) => { + const hits = response.hits. itens; + }, + (error) => { + console. race(error.message); + } +); +``` diff --git a/src/content/pages/pt-br/guide/migrating-4.mdx b/src/content/pages/pt-br/guide/migrating-4.mdx new file mode 100644 index 0000000000..086ca08ccc --- /dev/null +++ b/src/content/pages/pt-br/guide/migrating-4.mdx @@ -0,0 +1,662 @@ +--- +title: Mover para Expresso 4 +description: Um guia para migrar seus aplicativos Express.js da versão 3 para 4, cobrindo mudanças no middleware, roteamento e como atualizar sua base de código eficazmente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Expresso 4 é uma mudança quebrada do Express 3. Isso significa que um aplicativo Expresso 3 não funcionará se você atualizar a versão Expresso em suas dependências. + +Cobertos deste artigo: + + + +## Mudanças no Express 4 + +Há várias mudanças significativas na Expresso 4: + + + +Ver também: + +* [Novas funcionalidades em 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +* [Migrando da 3.x para a versão 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) + +### Alterações no núcleo do Express e sistema de middleware + +Express 4 no longer depends on Connect, and removes all built-in +middleware from its core, except for the `express.static` function. Isto significa que +Express agora é uma estrutura web de roteamento e middleware independente e +Versões e versões Express não são afetados por atualizações de middleware. + +Sem o intermediário integrado, você deve adicionar explicitamente todo o intermediário +que é necessário para executar seu aplicativo. Basta seguir estes passos: + +1. Instale o módulo: `npm install --save ` +2. Na sua aplicação, requer o módulo: `require('module-name')` +3. Use o módulo de acordo com sua documentação: `app.use( ... )` + +A seguinte tabela lista Express 3 middleware e seus homólogos no Express 4. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Expressar 3Express 4
+ express.bodyParser + + body-parser + + multer +
+ express.compress + + compressão +
+ express.cookieSession + + Ucookie-session +
+ express.cookieParser + + cookie-parser +
+ express.logger + + Morgan +
+ Uexpressão.sessão + + express-session +
+ express.favicon + + serve-favicon +
+ express.responseTime + + response-time +
+ express.errorHandler + + errorhandler +
+ express.methodOverride + + method-override +
+ express.timeout + + connect-timeout +
+ express.vhost + + vhost +
+ express.csrf + + csurf +
+ express.directory + + serve-index +
+ Uexpress.static + + Ave-estática +
+ +Aqui está a [lista completa](https://github.com/senchalabs/connect#middleware) de Express 4 middleware. + +Na maioria dos casos, você pode simplesmente substituir a versão antiga 3 middleware com +seu Expresso 4. Para obter detalhes, consulte a documentação do módulo no +GitHub. + +#### `app.use` aceita parâmetros + +Na versão 4 você pode usar um parâmetro variável para definir o caminho onde as funções de middleware são carregadas, em seguida, leia o valor do parâmetro a partir do manipulador de reta. +Por exemplo: + +```js +app.use('/book/:id', (req, res, next) => { + console.log('ID:', req.params.id); + next(); +}); +``` + +### O sistema de roteamento + +Apps agora carregam implicitamente roteando middleware, então você não tem mais que +se preocupar com a ordem em que o middleware é carregado em relação a +o middleware do `router`. + +A forma como você define rotas é inalterada, mas o sistema de roteamento tem dois +novos recursos para ajudar a organizar suas rotas: + +* Um novo método, `app.route()`, para criar gerenciadores de rotas em cadeia para um caminho de rota. +* Uma nova classe, `express.Router`, para criar modular montável handlers. + +#### Método `app.route()` + +O novo método `app.route()` permite que você crie gerenciadores de rotas +encadeáveis para um caminho de rota. Como o caminho é especificado em um único local, é útil criar rotas modulares, assim como reduzir a redundância e os tipos. Para obter mais informações +sobre rotas, consulte [`Router()` documentação](/en/4x/api#router). + +Aqui está um exemplo de manipuladores de rota encadeados que são definidos usando a função `app.route()`. + +```js +app + .route('/book') + .get((req, res) => { + res. end('Recebe um livro aleatório'); + }) + . ost((req, res) => { + res.send('Adicionar um livro'); + }) + . ut((req, res) => { + res.send('Atualizar o livro'); +}); +``` + +#### Classe `express.Router` + +O outro recurso que ajuda a organizar rotas é uma nova classe, +`express.Router`, que você pode usar para criar modular montável um controlador de rotas +. Uma instância `Router` é um sistema de roteamento de intermediários e +completo; por esta razão, é muitas vezes referido como um "mini-app". + +O exemplo a seguir cria um roteador como um módulo, carrega middleware em +ele, define algumas rotas e o conecta em um caminho no aplicativo principal. + +Por exemplo, crie um arquivo de roteador chamado `birds.js` no diretório de aplicativos, +com o seguinte conteúdo: + +```js +var express = require('express'); +var router = express.Router(); + +// middleware específico para este roteador +. se((req, res, ext) => { + console.log('Tempo:', Data. ow()); + next(); +}); +// define a rota da página inicial do roteador +. et('/', (req, res) => { + res.send('Birds home page'); +}); +// define a rota +roteador. et('/about', (req, res) => { + res.send('Sobre birds'); +}); + +module.exports = router; +``` + +Em seguida, carregue o módulo do roteador no aplicativo: + +```js +var birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +Agora o aplicativo será capaz de lidar com pedidos para os caminhos `/birds` e +`/birds/about`, e irá chamar o middleware `timeLog` +que é específico da rota. + +### Outras mudanças + +A tabela a seguir lista outras pequenas mas importantes mudanças no Express 4: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ObjectDescrição
Node.jsExpress 4 requer Node.js 0.10.x ou posterior e tem abandonado o suporte para Node.js 0.8.
`http.createServer()` + O módulo `http` não é mais necessário, a menos que você precise trabalhar diretamente com ele + (socket.io/SPDY/HTTPS). O aplicativo pode ser iniciado usando a função `app.listen()`. +
`app.configure()` + A função `app.configure()` foi removida. Use a função `process.env.NODE_ENV` ou + `app.get('env')` para detectar o ambiente e configurar o aplicativo de acordo. +
`espaços json` + A propriedade de aplicação `json spaces` está desativada por padrão no Express 4. +
`req.accepted()` + Use `req.accepts()`, `req.acceptsEncodings()`, `req.acceptsCharsets()`, e + `req.acceptsLanguages()`. +
`res.location()`Não resolve mais URLs relativas.
`req.params`Era um array; agora um objeto.
`res.locals`Era uma função; agora um objeto.
`res.headerSent`Alterado para `res.headers`.
`app.route`Agora disponível como `app.mountpath`.
`res.on('header')`removido.
`res.charset`removida.
`res.setHeader('Set-Cookie', val)` + A funcionalidade agora está limitada a definir o valor básico de cookie. Use `res.cookie()` para adicionar + funcionalidade. +
+ +## Exemplo de migração de aplicativos + +Aqui está um exemplo de migração de um aplicativo Express 3 para o Express 4. +Os arquivos de interesse são `app.js` e `package.json`. + +### Versão 3 do aplicativo + +#### `app.js` + +Considere um aplicativo Express v.3 com o seguinte arquivo `app.js`: + +```js +var express = require('express'); +var routes = require('./routes'); +var usuário = require('. routes/user'); +var http = require('http'); +var path = require('path'); + +var app = express(); + +// todos os ambientes +app. et('porta', process.env.PORT ├3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(express.favicon()); +app.use(express.logger('dev')); +app.use(express.methodOverride()); +app.use(express. ession({ secret: 'your secret here' })); +app.use(express.bodyParser()); +app.use(app.router); +app.use(express. tatic(path.join(__dirname, 'public'))); + +// desenvolvimento apenas +if (app.get('env') === 'development') { + app. se(express.errorHandler()); +} + +app.get('/', routes.index); +app.get('/users', user.list); + +http. reateServer(app).listen(app.get('port'), () => { + console.log('Servidor expresso escutando na porta ' + app.get('port')); +}); +``` + +#### `package.json` + +O arquivo de acompanhamento da versão 3 `package.json` pode parecer +algo como isto: + +```json +{ + "name": "application-name", + "version": "0.0. ", + "private": true, + "scripts": { + "start": "node app. " + }, + "dependencies": { + "express": "3. 2.0", + "pug": "*" + } +} +``` + +### processo + +Inicie o processo de migração instalando o middleware necessário para o aplicativo +Express 4 e atualize o Express e o Pug para sua respectiva versão +mais recente com o seguinte comando: + +```bash +$ npm install serve-favicon morgan method-override express-session body-parser multer errorhandler express@latest pug@latest --save +``` + +Faça as seguintes alterações no `app.js`: + +1. As funções embutidas do Express middleware `express.favicon`, + `express.logger`, `express.methodOverride`, + `express.session`, `express.bodyParser` e + `express.errorHandler` não estão mais disponíveis no objeto + `express`. Você deve instalar suas alternativas + manualmente e carregá-las no aplicativo. + +2. Você não precisa mais carregar a função `app.router`. + Não é um objeto de aplicativo Expresso 4, então remova o código + `app.use(app.router);`. + +3. Certifique-se de que as funções de middleware estão carregadas na ordem correta - carregue o `errorHandler` após carregar as rotas do aplicativo. + +### Versão 4 do aplicativo + +#### `package.json` + +Executar o comando `npm` acima atualizará o `package.json` da seguinte forma: + +```json +{ + "name": "application-name", + "version": "0.0. ", + "private": true, + "scripts": { + "start": "node app. " + }, + "dependencies": { + "body-parser": "^1.5.2", + "errorhandler": "^1.1. ", + "express": "^4.8.0", + "express-session": "^1. .2", + "put": "^2.0.0", + "override-método": "^2. .2", + "morgan": "^1.2.2", + "multer": "^0.1. ", + "serve-favicon": "^2.0.1" + } +} +``` + +#### `app.js` + +Then, remove invalid code, load the required middleware, and make other +changes as necessary. O arquivo `app.js` será parecido com este: + +```js +var http = require('http'); +var express = require('express'); +var routes = require('./routes'); +var user = require('./routes/user'); +var path = require('path'); + +var favicon = require('serve-favicon'); +var logger = require('morgan'); +var methodOverride = require('method-override'); +var session = require('express-session'); +var bodyParser = require('body-parser'); +var multer = require('multer'); +var errorHandler = require('errorhandler'); + +var app = express(); + +// all environments +app.set('port', process.env.PORT || 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(favicon(path.join(__dirname, '/public/favicon.ico'))); +app.use(logger('dev')); +app.use(methodOverride()); +app.use( + session({ + resave: true, + saveUninitialized: true, + secret: 'uwotm8', + }) +); +app.use(bodyParser.json()); +app.use(bodyParser.urlencoded({ extended: true })); +app.use(multer()); +app.use(express.static(path.join(__dirname, 'public'))); + +app.get('/', routes.index); +app.get('/users', user.list); + +// error handling middleware should be loaded after the loading the routes +if (app.get('env') === 'development') { + app.use(errorHandler()); +} + +var server = http.createServer(app); +server.listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + + +A menos que você precise trabalhar diretamente com o módulo 'http' (socket.io/SPDY/HTTPS), carregá-lo não é necessário, e o aplicativo pode ser simplesmente iniciado dessa forma: + +```js +app.listen(app.get('port'), () => { + console.log('Servidor Express escutando na porta ' + app.get('port')); +}); +``` + + + +### Executar o aplicativo + +O processo de migração está completo, e o aplicativo agora é um aplicativo +Express 4. Para confirmar, inicie o aplicativo usando o seguinte comando: + +```bash +$ nó . +``` + +Carregue [http://localhost:3000](http://localhost:3000) +e veja a página inicial sendo renderizada pelo Express 4. + +## Atualizando para o gerador de aplicativos Express 4 + +A ferramenta de linha de comando para gerar um app Express ainda é +`express`, mas para atualizar para a nova versão, você deve desinstalar +o gerador de aplicativo Express 3 e então instalar o novo gerador +`express-generator`. + +### Instalando + +Se você já tiver o gerador de aplicativo Express 3 instalado em seu sistema, +você deve desinstalá-lo: + +```bash +$ npm desinstale -g expresso +``` + +Dependendo de como seus privilégios de arquivo e diretório são configurados, +talvez você precise executar este comando com `sudo`. + +Agora instale o novo gerador: + +```bash +$ npm install -g express-generator +``` + +Dependendo de como seus privilégios de arquivo e diretório são configurados, +talvez você precise executar este comando com `sudo`. + +Agora o comando `express` no seu sistema é atualizado para o gerador +Express 4. + +### Alterações no gerador de aplicativos + +Opções de comando e uso em grande parte permanecem iguais, com as seguintes exceções: + +* A opção `--sessions` foi removida. +* A opção `--jshtml` foi removida. +* Adicionado a opção `--hogan` para apoiar [Hogan.js](http://twitter.github.io/hogan.js/). + +### Exemplo + +Execute o seguinte comando para criar um aplicativo Express 4: + +```bash +$ app4 expresso +``` + +Se você olhar o conteúdo do arquivo `app4/app.js`, você notará +que todas as funções de middleware (exceto `expressos. tatic`) que são necessários para +o aplicativo são carregados como módulos independentes, e o 'router' middleware +não está mais carregado explicitamente no aplicativo. + +Você também vai notar que o arquivo `app.js` agora é um Node. módulo s, em contraste com o app autônomo gerado pelo gerador antigo. + +Depois de instalar as dependências, inicie o aplicativo usando o seguinte comando: + +```bash +$ início do npm +``` + +Se você olhar o script `npm start` no `package. arquivo son`, +você notará que o comando real que inicia o aplicativo é +`node . bin/www`, que costumava ser `node app.js` +no Express 3. + +Porque o arquivo `app.js` que foi gerado pelo gerador Express 4 +agora é um Node. Módulo s não pode mais ser iniciado de forma independente como um aplicativo +(a menos que você modifique o código). O módulo deve ser carregado em um arquivo Node.js +e iniciado via arquivo Node.js. O arquivo Node.js é `./bin/www` +neste caso. + +Nem o diretório `bin` nem o arquivo `www` +sem extensão são obrigatórios para a criação de um aplicativo Express ou para iniciar o aplicativo. They are +just suggestions made by the generator, so feel free to modify them to suit your +needs. + +Para se livrar do diretório `www` e manter as coisas no caminho "Express 3", +apague a linha que diz `módulo. xports = app;` no final do arquivo +`app.js`, e então cole o seguinte código em seu lugar: + +```js +app.set('port', process.env.PORT →3000); + +var server = app.listen(app.get('port'), () => { + debug('Expresse servidor escutando na porta ' + server.address().port); +}); +``` + +Certifique-se de carregar o módulo `debug` no topo do arquivo `app.js` usando o seguinte código: + +```js +var debug = require('debug')('app4'); +``` + +Em seguida, mude `"start": "node ./bin/www"` no arquivo `package.json` para `"start": "node app.js"`. + +Você moveu a funcionalidade `./bin/www` de volta para +`app.js`. Esta mudança não é recomendada, mas o exercício ajuda você +a entender como o `. arquivo bin/www` funciona, e porque o arquivo `app.js` +não inicia mais por conta própria. diff --git a/src/content/pages/pt-br/guide/migrating-5.mdx b/src/content/pages/pt-br/guide/migrating-5.mdx new file mode 100644 index 0000000000..97c2021060 --- /dev/null +++ b/src/content/pages/pt-br/guide/migrating-5.mdx @@ -0,0 +1,678 @@ +--- +title: Movendo para Expresso 5 +description: Um guia completo para migrar seus aplicativos Express.js da versão 4 a 5, detalhando alterações quebraduras, métodos obsoletos e novas melhorias. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Expresso 5 não é muito diferente do Express 4; embora ele mantenha a mesma API básica, ainda há mudanças que quebram a compatibilidade com a versão anterior. Portanto, um aplicativo construído com Express 4 pode não funcionar se você atualizá-lo para usar o Express 5. + +Para instalar esta versão, você precisa ter uma versão 18 ou superior de Node.js. Em seguida, execute o seguinte comando em seu diretório de aplicativos: + +```sh +npm install "express@5" +``` + +Você pode então executar seus testes automatizados para ver o que falhou e corrigir problemas de acordo com as atualizações listadas abaixo. Após falhas no teste, execute seu aplicativo para ver quais erros ocorrem. Você vai descobrir imediatamente se o aplicativo usa quaisquer métodos ou propriedades que não são suportadas. + +## Expresse 5 Codemods + +Para ajudá-lo a migrar seu servidor expresso, nós criamos um conjunto de codemods que irão ajudá-lo a atualizar automaticamente seu código para a última versão do Express. + +Execute o seguinte comando para executar todos os codemods disponíveis: + +```sh +npx codemod@latest @expressjs/v5-migration-recipe +``` + +Se você quiser executar um código específico, você pode executar o seguinte comando: + +```sh +npx codemod@latest @expressjs/name-of-the-codemod +``` + +Você pode encontrar a lista de codemods disponíveis [here](https://codemod.link/express). + +## Mudanças no Express 5 + +**Métodos e propriedades removidos** + + + +**Mudou** + + + +**Melhorias** + + + +## Métodos e propriedades removidos + +Se você usar qualquer um desses métodos ou propriedades em seu aplicativo, ele irá falhar. Então, você precisará alterar seu aplicativo depois que você atualizar para a versão 5. + +### app.del() + +Expresso 5 não suporta mais a função `app.del()`. Se você usa essa função, um erro é lançado. Para registrar as rotas HTTP DELETE, use a função `app.delete()`. + +Inicialmente, `del` foi usado em vez de `delete`, porque `delete` é uma palavra-chave reservada em JavaScript. Entretanto, a partir do ECMAScript 6, `apagar` e outras palavras-chave reservadas podem ser usadas legalmente como nomes de propriedades. + + +Você pode substituir as assinaturas obsoletas pelo seguinte comando: + +```plaintext +npx codemod@latest @expressjs/route-del-to-delete +``` + + + +```js +// v4 +app.del('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); + +// v5 +app. elete('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); +``` + +### app.param(fn) + +A assinatura `app.param(fn)` foi usada para modificar o comportamento da função `app.param(name, fn)`. Está obsoleto desde a versão 4.11.0, e Express 5 não apoia mais nada. + +### Nomes de métodos plurais + +Os nomes dos seguintes métodos foram pluralizados. No Express 4, a utilização dos métodos antigos resultou em um aviso de depreciação. Expresso 5 não os suporta de forma alguma: + +`req.acceptsCharset()` foi substituído por `req.acceptsCharsets()`. + +`req.acceptsEncoding()` é substituído por `req.acceptsEncodings()`. + +`req.acceptsLanguage()` foi substituído por `req.acceptsLanguages()`. + + +Você pode substituir as assinaturas obsoletas pelo seguinte comando: + +```plaintext +npx codemod@latest @expressjs/pluralize-method-names +``` + + + +```js +// v4 +app.all('/', (req, res) => { + req.acceptsCharset('utf-8'); + req. cceptsEncoding('br'); + req.acceptsLanguage('en'); + + // ... +}); + +// v5 +app. ll('/', (req, res) => { + req.acceptsCharsets('utf-8'); + req.acceptsEncodings('br'); + req.acceptsLanguages('en'); + + // ... +}); +``` + +### Posicionando dois pontos (:) no nome do app.param(name, fn) + +Um personagem com dois pontos principais (:) no nome do `app. aram(name, fn)` é um remanescente do Express 3, e por uma questão de compatibilidade retrógrada, Express 4 apoiou-o com um aviso de depreciação. Expresso 5 irá ignorá-lo silenciosamente e usar o parâmetro de nome sem prefixá-lo com dois-pontos. + +Isso não deve afetar o seu código se você seguir a documentação Express 4 do [app.param](/en/4x/api#app.param), uma vez que não faz qualquer menção ao casal principal. + +### req.param(nome) + +Este método potencialmente confuso e perigoso de recuperação de dados de formulários foi removido. Agora você precisará procurar especificamente o nome do parâmetro enviado em `req.params`, `req.body`, ou `req.query`. + + +Você pode substituir as assinaturas obsoletas pelo seguinte comando: + +```plaintext +npx codemod@latest @expressjs/explicit-request-params +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + const id = req.param('id'); + const body = req. aram('body'); + const query = req.param('query'); + + // ... +}); + +// v5 +app.post('/user', (req, res) => { + const id = req.params. d; + const body = req.body; + const query = req.query; + + // ... +}); +``` + +### res.json(obj, status) + +Expresso 5 não suporta mais a assinatura `res.json(obj, status)`. Ao invés disso, defina o status e então encadee-o ao método `res.json()` como este: `res.status(status).json(obj)`. + + +Você pode substituir as assinaturas obsoletas pelo seguinte comando: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.json({ name: 'Ruben' }, 201); +}); + +// v5 +aplicativo. ost('/user', (req, res) => { + res.status(201).json({ name: 'Ruben' }); +}); +``` + +### res.jsonp(obj, status) + +Expresso 5 não suporta mais a assinatura `res.jsonp(obj, status)`. Ao invés disso, defina o status e então encadee-o ao método `res.jsonp()` como este: `res.status(status).jsonp(obj)`. + + +Você pode substituir as assinaturas obsoletas pelo seguinte comando: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.jsonp({ name: 'Ruben' }, 201); +}); + +// v5 +app.post('/user', (req, res) => { + res.status(201).jsonp({ name: 'Ruben' }); +}); +``` + +### res.redirect(url, status) + +Expresso 5 não suporta mais a assinatura `res.redirect(url, status)`. Ao invés disso, use a seguinte assinatura: `res.redirect(status, url)`. + + +Você pode substituir as assinaturas obsoletas pelo seguinte comando: + +```plaintext +npx codemod@latest @expressjs/redirect-arg-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('/users', 301); +}); + +// v5 +app. et('/user', (req, res) => { + res.redirect(301, '/users'); +}); +``` + +### res.redirect('voltar') e res.location('voltar') + +Expresse 5 não suporta mais a string mágica `back` nos métodos `res.redirect()` e `res.location()`. Ao invés disso, use o valor `req.get('Referrer') ahead '/'` para redirecionar de volta para a página anterior. No Express 4, os métodos `res.redirect('back')` e `res.location('back')` foram descontinuados. + + +Você pode substituir as assinaturas obsoletas pelo seguinte comando: + +```plaintext +npx codemod@latest @expressjs/back-redirect-deprecated +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('back'); +}); + +// v5 +app. et('/user', (req, res) => { + res.redirect(req.get('Referrer') ├'/'); +}); +``` + +### res.send(corpo estado) + +Expresso 5 não suporta mais a assinatura `res.send(obj, status)`. Em vez disso, defina o status e então encadeie com o método `res.send()` como este: `res.status(status).send(obj)`. + + +Você pode substituir as assinaturas obsoletas pelo seguinte comando: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send({ name: 'Ruben' }, 200); +}); + +// v5 +app. et('/user', (req, res) => { + res.status(200).send({ name: 'Ruben' }); +}); +``` + +### res.send(status) + +Expresso 5 não suporta mais a assinatura `res.send(status)`, onde `status` é um número. Ao invés disso, use os `res. função endStatus(statusCode)`, que define o código de status do cabeçalho de resposta HTTP e envia o texto da versão do código: "Não encontrado", "Erro interno do servidor", e assim por diante. +Se você precisar enviar um número usando os `res. função end()`, cita o número para convertê-lo em uma string, para que o Express não interprete como uma tentativa de usar a antiga assinatura não suportada. + + +Você pode substituir as assinaturas obsoletas pelo seguinte comando: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send(200); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendStatus(200); +}); +``` + +### res.sendfile() + +A função `res.sendfile()` foi substituída por uma versão caída por camelo `res.sendFile()` no Express 5. + +**Nota:** No Expresso 5, `res. endFile()` usa o pacote `mime-types` para detecção do tipo MIME que retorna valores diferentes de Content-Type que Expresso 4 para vários tipos de arquivo comuns: + +* Arquivos JavaScript (.js): agora "text/javascript" ao invés de "application/javascript" +* Arquivos JSON (.json): agora "application/json" em vez de "text/json" +* Arquivos CSS (.css): agora "text/css" em vez de "text/plain" +* Arquivos XML (.xml): agora "application/xml" em vez de "text/xml" +* Arquivos de fonte (.woff): agora "font/woff" em vez de "application/font-woff" +* Arquivos SVG (.svg): agora "image/svg+xml" em vez de "application/svg+xml" + + +Você pode substituir as assinaturas obsoletas pelo seguinte comando: + +```plaintext +npx codemod@latest @expressjs/camelcase-sendfile +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.sendfile('/path/to/file'); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendFile('/path/to/file'); +}); +``` + +### router.param(fn) + +A assinatura `router.param(fn)` foi usada para modificar o comportamento da função `router.param(name, fn)`. Está obsoleto desde a versão 4.11.0, e Express 5 não apoia mais nada. + +### express.static.mime + +No Express 5, `mime` não é mais uma propriedade exportada do campo `static`. +Use o [pacote `mime-types`](https://github.com/jshttp/mime-types) para trabalhar com valores do tipo MIME. + +**Importante:** Esta alteração afeta não apenas o uso direto de `express.static.mime`, mas também outros métodos Express que dependem da detecção de tipo MIME como `res.sendFile()`. Os seguintes tipos MIME mudaram de Express 4: + +* Arquivos JavaScript (.js): agora servido como "text/javascript" em vez de "application/javascript" +* Arquivos JSON (.json): agora servido como "application/json" em vez de "text/json" +* Arquivos CSS (.css): agora servido como "text/css" em vez de "text/plain" +* Arquivos HTML (): agora servido como "text/html; charset=utf-8" ao invés de apenas "text/html" +* Arquivos XML (.xml): agora servido como "application/xml" ao invés de "text/xml" +* Arquivos de fonte (.woff): agora servido como "font/woff" em vez de "application/font-woff" + +```js +// v4 +express.static.mime.lookup('json'); + +// v5 +const mime = require('mime-types'); +mime.lookup('json'); +``` + +### expressão:roteador logs de depuração + +No Express 5, a lógica de manipulação do roteador é realizada por uma dependência. Portanto, os logs de depuração +para o roteador não estão mais disponíveis sob o namespace 'expresso'. +No v4, os logs estavam disponíveis sob os namespaces `express:router`, `express:router:layer`, +e `express:router:route`. Todos esses foram incluídos sob o namespace `express:*`. +Na v5.1+, os logs estão disponíveis sob o namespaces `router`, `router:layer` e `router:route`. +Os logs de `roteador:layer` e `router:route` estão incluídos no namespace `router:*`. +Para alcançar os mesmos detalhes do log de depuração ao usar `express:*` no v4, use uma combinação de +`express:*`, `router` e `router:*`. + +```sh + +DEBUG=express:* node index.js + + +DEBUG=express:*,router,router:* node index.js +``` + +## Alterado + +### Caminho de rota correspondente + +A sintaxe de rota de correspondência de um caminho é quando uma string é fornecida como o primeiro parâmetro para o `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, and `router.use()` APIs. As seguintes alterações foram feitas em como a seqüência de caracteres de caminho é combinada para uma solicitação de entrada: + +* O caractere curinga `*` deve ter um nome, correspondendo ao comportamento dos parâmetros `:`, use `/*splat` em vez de `/*` + +```js +// v4 +app.get('/*', async (req, res) => { + res.send('ok'); +}); + +// v5 +app. et('/*splat', async (req, res) => { + res.send('ok'); +}); +``` + + +`*splat` corresponde a qualquer caminho sem o caminho raiz. Caso você precise coincidir com o caminho raiz também `/`, você pode usar `/{*splat}`, envolvendo o caractere curinga nos quadros. + +```js +// v5 +app.get('/{*splat}', async (req, res) => { + res.send('ok'); +}); +``` + + + +* O caractere opcional `?` não é mais suportado, use chaves em vez disso. + +```js +// v4 +app.get('/:file.:ext?', async (req, res) => { + res.send('ok'); +}); + +// v5 +app.get('/:file{.:ext}', async (req, res) => { + res.send('ok'); +}); +``` + +* Caracteres Regexp não são suportados. Por exemplo: + +```js +app.get('/[discussionőpage]/:slug', async (req, res) => { + res.status(200).send('ok'); +}); +``` + +deve ser alterado para: + +```js +app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { + res.status(200).send('ok'); +}); +``` + +* Alguns personagens foram reservados para evitar confusão durante a atualização (`()[]?+!`), use `\` para escapá-los. +* Os nomes de parâmetros agora suportam identificadores JavaScript válidos, ou citados como `:"isto"`. + +### promessas rejeitadas tratadas de intermediários e manipuladores + +Solicite aos manipuladores e manipuladores que retornam promessas rejeitadas agora são tratados encaminhando o valor rejeitado como um `Erro` para o erro de manipulação do middleware. Isto significa que usar funções `async` como middleware e manipuladores são mais fáceis do que nunca. Quando um erro é lançado em uma função `async` ou uma promessa rejeitada é `aguardada` dentro de uma função async esses erros serão passados para o manipulador de erro como se chamando `next(err)`. + +Detalhes de como Expresso lida com os erros está coberto na [documentação de manipulação de erro](/en/guide/error-handling). + +### expres.urlencoded + +O método `express.urlencoded` torna a opção `estendida` `false` por padrão. + +### dotfiles express.static + +No Expresso 5, a opção `express.static` do middleware `dotfiles` agora padrão é `"ignore"`. Isto é uma alteração do Express 4, onde os dotfiles foram servidos por padrão. Como resultado, arquivos dentro de um diretório que começa com um ponto (`.`), como `. ell-known`, não será mais acessível e retornará um erro **404 Não Encontrado**. Isso pode quebrar funcionalidade que depende de servir diretórios de pontos, como Android App Links, e Apple Universal Links. + +Exemplo de código de quebra: + +```js +// v4 +app.use(express.static('public')); +``` + +Depois de migrar para o Express 5, um pedido para `/.well-known/assetlinks.json` resultará em uma **404 Não Encontrado**. + +Para corrigir isso, sirva diretórios de pontos específicos usando explicitamente os `dotfiles: "allow"` option: + +```js +// v5 +app.use('/.well-known', express.static('public/.well-known', { dotfiles: 'allow' })); +app.use(express.static('public')); +``` + +Esta abordagem permite que você sirva com segurança apenas os diretórios de pontos pretendidos, mantendo o comportamento seguro padrão para outros dotfiles, que permanecem inacessíveis. + +### Ouvir + +No Express 5, o método `app.listen` invocará a função de callback fornecido pelo usuário (se fornecido) quando o servidor receber um evento de erro. Na Expressa 4, esses erros seriam lançados. Essa mudança desloca a responsabilidade da manipulação de erros para a função de retorno de chamada no Express 5. Se houver um erro, ele será passado para o callback como argumento. +Por exemplo: + +```js +const server = app.listen(8080, '0.0.0.0', (error) => { + if (error) { + throw erro; // ex. EADDRINUSE + } + console.log(`Ouvindo em ${JSON.stringify(server.address())}`); +}); +``` + +### app.router + +O objeto `app.router`, que foi removido no Express 4, retornou no Express 5. Na nova versão, este objeto é apenas uma referência ao roteador básico Express, Ao contrário do Express 3, onde um aplicativo teve que carregá-lo explicitamente. + +### req.corpo + +A propriedade `req.body` retorna `undefined` quando o corpo não foi analisado. No Express 4, por padrão ele retorna `{}`. + +### req.anfitrião + +No Express 4, a função `req.host` incorretamente retirou o número da porta se estivesse presente. No Express 5, o número da porta é mantido. + +### req.params + +O objeto `req.params` agora tem um **protótipo nulo** ao usar caminhos de string. No entanto, se o caminho é definido com uma expressão regular, `req.params` permanece um objeto padrão com um protótipo normal. Além disso, existem duas mudanças comportamentais importantes: + +**Os parâmetros coringa agora são arrays:** + +Caracteres curinga (por exemplo, `/*splat`) capturam segmentos de caminho como um array em vez de uma única string. + +```js +app.get('/*splat', (req, res) => { + // GET /foo/bar + console.dir(req. arams); + // => [Objeto: null prototype] { splat: [ 'foo', 'bar' ] } +}); +``` + +**Parâmetros não correspondentes são omitidos:** + +No Expresso 4, os caracteres curinga eram strings vazias (`''`) e parâmetros opcionais `:` (usando `?`) tinham uma chave com valor `undefined`. No Expresso 5, parâmetros não correspondentes são completamente omitidos de `req.params`. + +```js +// v4: curinga sem comparação é uma string vazia +app.get('/*', (req, res) => { + // GET / + console.dir(req. arams); + // => { '0': '' } +}); + +// v4: parâmetro opcional não correspondente é indefinido +aplicativo. et('/:file.:ext?', (req, res) => { + // GET /image + console. ir(req.params); + // => { file: 'image', ext: undefined } +}); + +// v5: param opcional não comparado é omitido +app.get('/:file{. ext}', (req, res) => { + // GET /image + console.dir(req. arams); + // => [Object: null prototype] { file: 'image' } +}); +``` + +### req.consulta + +A propriedade `req.query` não é mais uma propriedade gravável e em vez disso é um getter. O analisador de consulta padrão foi alterado de "estendido" para "simples". + +### res.clearCookie + +O método `res.clearCookie` ignora as opções `maxAge` e `expires` fornecidas pelo usuário. + +### status.res.status + +O método `res.status` só aceita inteiros no intervalo de `100` para `999`, seguindo o comportamento definido pelo Node. , e retorna um erro quando o código de status não é um inteiro. + +### variável.variação + +O 'res.vary' lança um erro quando o argumento 'field' está faltando. No Express 4, se o argumento foi omitido, ele deu um aviso no console + +## Melhorias + +### res.render() + +Este método agora exige comportamento assíncrono para todos os motores de visualização, evitando erros causados por mecanismos de visualização que tiveram uma implementação síncrona e que violaram a interface recomendada. + +### Suporte à codificação Brotli + +Expresso 5 suporta a codificação Brotli para solicitações recebidas de clientes que suportam isso. diff --git a/src/content/pages/pt-br/resources/glossary.mdx b/src/content/pages/pt-br/resources/glossary.mdx new file mode 100644 index 0000000000..0a5089e6d3 --- /dev/null +++ b/src/content/pages/pt-br/resources/glossary.mdx @@ -0,0 +1,61 @@ +--- +title: Glossary +description: Um glossário abrangente de termos relacionados ao Express.js, Node.js, middleware, routing e outros conceitos-chave para ajudá-lo a entender e usar o Express eficazmente. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +### aplicativo + +Em geral, um ou mais programas que são projetados para realizar operações para uma finalidade específica. No contexto da Express, um programa que usa o API Express executando na plataforma Node.js. Também pode se referir a um [objeto do aplicativo](/en/api#express). + +### API + +Interface de programação de aplicativos. Feitiço a abreviação quando ela for usada pela primeira vez. + +### Expresso + +Uma rápida, não-opinionada e minimalista estrutura web para aplicativos Node.js. Em geral, "Expresso" é preferida a "Express.js", embora este último seja aceitável. + +### libuv + +Uma biblioteca de suporte multiplataforma focada em E/O assíncrono, desenvolvida principalmente para uso pelo Node.js. + +### middleware + +Uma função que é invocada pela camada de roteamento Express antes do manipulador de requisições final, e assim situa-se no meio entre um pedido em bruto e a rota final pretendida. Alguns belos pontos de terminologia em torno do middleware: + +* `var foo = require('middleware')` é chamado de *requiring* ou *usando* um módulo Node.js. Então, a instrução `var mw = foo()` normalmente retorna o middleware. +* `app.use(mw)` é chamado de *adicionando o middleware à pilha de processamento global*. +* `app.get('/foo', mw, função (req, res) { ... })` é chamado de *adicionando o middleware para a pilha de processamento "GET /foo"*. + +### Node.js + +Uma plataforma de software usada para construir aplicações de rede escaláveis. Node.js usa JavaScript como sua linguagem de script e alcança alta taxa de transferência através de I/O não bloqueando e de um loop de eventos uni-la-thread. Ver [nodejs.org](https://nodejs.org/en/). **Nota de uso**: Inicialmente, "Node.js", em seguida, "Node". + +### código aberto, código aberto + +Quando usado como adjetivo, hífene; por exemplo: "Este é um software de código aberto". Veja [Software de código aberto na Wikipedia](http://en.wikipedia.org/wiki/Open-source_software). + + + +Embora seja comum não fazer hifenização deste termo, estamos usando as regras padrão em inglês para +hifenização de um adjetivo composto. + + + +### solicitação + +Um pedido HTTP. Um cliente envia uma mensagem de solicitação HTTP para um servidor, que retorna uma resposta. A solicitação deve usar um dos vários [métodos de requisição](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) como GET, POST, e assim por diante. + +### Resposta + +Uma resposta HTTP. Um servidor retorna uma mensagem de resposta HTTP para o cliente. A resposta contém informações de estado de conclusão sobre o pedido e também pode conter conteúdo solicitado em seu corpo da mensagem. + +### rota + +Parte de uma URL que identifica um recurso. Por exemplo, em `http://foo.com/products/id`, "/products/id" é a rota. + +### roteador + +Ver [router](/en/api#router) na referência da API. diff --git a/src/content/pages/pt-br/resources/utils.md b/src/content/pages/pt-br/resources/utils.md new file mode 100644 index 0000000000..51999b62f0 --- /dev/null +++ b/src/content/pages/pt-br/resources/utils.md @@ -0,0 +1,22 @@ +--- +title: Utilidades Expressas +description: Descubra módulos de utilitários relacionados ao Express.js e Node.js, incluindo ferramentas para cookies, proteção CSRF, análise de URLs, roteamento e muito mais para melhorar seus aplicativos. +--- + +## Funções do utilitário expresso + +A organização [pillarjs](https://github.com/pillarjs) do GitHub contém um número de módulos +para funções utilitárias que podem ser úteis em geral. + +| Módulos utilitários | Descrição: | +| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [cookies](https://www.npmjs.com/package/cookies) | Obter e definir cookies HTTP(S) que podem ser assinados para evitar manipulação, usando Keygrip. Pode ser usado com a biblioteca HTTP do Node.js ou como Express middleware. | +| [csrf](https://www.npmjs.com/package/csrf) | Contém a lógica por trás da criação e verificação de tokens CSRF. Use este módulo para criar um middleware de CSRF personalizado. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Função a invocar como o passo final para responder a requisição HTTP. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Analisar uma URL com cache. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Transforme uma string de caminho estilo Express, como \`\`/user/:name\` em uma expressão regular. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Resolve um caminho relativo contra um caminho raiz com validação. | +| [router](https://www.npmjs.com/package/router) | Roteador simples ao estilo de middleware. | +| [send](https://www.npmjs.com/package/send) | Biblioteca para streaming de arquivos como uma resposta HTTP, com suporte para respostas parciais (intervalos), negociação condicional-GET e eventos granulares. | + +Para módulos adicionais de baixo nível relacionados à HTTP, consulte [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/pt-br/support.md b/src/content/pages/pt-br/support.md new file mode 100644 index 0000000000..eac7160c46 --- /dev/null +++ b/src/content/pages/pt-br/support.md @@ -0,0 +1,23 @@ +--- +title: Suporte à Versão +description: Encontre informações sobre o cronograma de suporte para diferentes versões do Express.js, incluindo quais versões são atualmente mantidas e políticas em fim de vida. +--- + +Somente a versão mais recente de qualquer linha de lançamento principal é suportada. + +Versões que são EOL (fim de vida) _pode_ receber atualizações de vulnerabilidades de segurança críticas, mas a equipe Express não oferece garantia e não planeja endereçar ou liberar correções para quaisquer problemas encontrados. + +| Versão maior | Versão mínima do Node.js | Início Suporte | Término Suporte | +| ------------------------------------------- | ---------------------------------------- | ---------------- | ---------------- | +| [**v5.x**](/en/5x/api) | 18 | Setembro de 2024 | **em andamento** | +| [**v4.x**](/en/4x/api) | 0.10.0 | Abril de 2014 | **em andamento** | +| [**v3.x**](/en/3x/api) | 0.8.0 | Outubro de 2012 | Julho de 2015 | +| [**v2.x**](/2x/) | 0.4.1 | Março de 2011 | Julho de 2012 | +| **v1.x** | 0.2.0 | Dezembro de 2010 | Março de 2011 | +| **v0.14.x** | 0.1.98 | Dezembro de 2010 | Dezembro de 2010 | + +## Opções de Suporte Comercial + +Se você não puder atualizar para uma versão suportada do Express, entre em contato com um de nossos parceiros para receber atualizações de segurança: + +- [Suporte para HeroDevs Final Interminável](http://www.herodevs.com/support/express-nes?utm_source=expressjs&utm_medium=link&utm_campaign=express_eol_page) diff --git a/src/content/pages/zh-tw/advanced/best-practice-performance.md b/src/content/pages/zh-tw/advanced/best-practice-performance.md new file mode 100644 index 0000000000..a98c7fcf6a --- /dev/null +++ b/src/content/pages/zh-tw/advanced/best-practice-performance.md @@ -0,0 +1,305 @@ +--- +title: 'Production best practices: performance and reliability' +description: Discover performance and reliability best practices for Express apps in production, covering code optimizations and environment setups for optimal performance. +--- + +This article discusses performance and reliability best practices for Express applications deployed to production. + +This topic clearly falls into the "devops" world, spanning both traditional development and operations. Accordingly, the information is divided into two parts: + +- Things to do in your code (the dev part): + - [Use gzip compression](#use-gzip-compression) + - [Don't use synchronous functions](#dont-use-synchronous-functions) + - [Do logging correctly](#do-logging-correctly) + - [Handle exceptions properly](#handle-exceptions-properly) +- Things to do in your environment / setup (the ops part): + - [Set NODE_ENV to "production"](#set-node_env-to-production) + - [Ensure your app automatically restarts](#ensure-your-app-automatically-restarts) + - [Run your app in a cluster](#run-your-app-in-a-cluster) + - [Cache request results](#cache-request-results) + - [Use a load balancer](#use-a-load-balancer) + - [Use a reverse proxy](#use-a-reverse-proxy) + +## Things to do in your code + +Here are some things you can do in your code to improve your application's performance: + +- [Use gzip compression](#use-gzip-compression) +- [Don't use synchronous functions](#dont-use-synchronous-functions) +- [Do logging correctly](#do-logging-correctly) +- [Handle exceptions properly](#handle-exceptions-properly) + +### Use gzip compression + +Gzip compressing can greatly decrease the size of the response body and hence increase the speed of a web app. Use the [compression](https://www.npmjs.com/package/compression) middleware for gzip compression in your Express app. For example: + +```js +const compression = require('compression'); +const express = require('express'); +const app = express(); + +app.use(compression()); +``` + +For a high-traffic website in production, the best way to put compression in place is to implement it at a reverse proxy level (see [Use a reverse proxy](#use-a-reverse-proxy)). In that case, you do not need to use compression middleware. For details on enabling gzip compression in Nginx, see [Module ngx_http_gzip_module](http://nginx.org/en/docs/http/ngx_http_gzip_module) in the Nginx documentation. + +### Don't use synchronous functions + +Synchronous functions and methods tie up the executing process until they return. A single call to a synchronous function might return in a few microseconds or milliseconds, however in high-traffic websites, these calls add up and reduce the performance of the app. Avoid their use in production. + +Although Node and many modules provide synchronous and asynchronous versions of their functions, always use the asynchronous version in production. The only time when a synchronous function can be justified is upon initial startup. + +You can use the `--trace-sync-io` command-line flag to print a warning and a stack trace whenever your application uses a synchronous API. Of course, you wouldn't want to use this in production, but rather to ensure that your code is ready for production. See the [node command-line options documentation](https://nodejs.org/api/cli#cli_trace_sync_io) for more information. + +### Do logging correctly + +In general, there are two reasons for logging from your app: For debugging and for logging app activity (essentially, everything else). Using `console.log()` or `console.error()` to print log messages to the terminal is common practice in development. But [these functions are synchronous](https://nodejs.org/api/console#console) when the destination is a terminal or a file, so they are not suitable for production, unless you pipe the output to another program. + +#### For debugging + +If you're logging for purposes of debugging, then instead of using `console.log()`, use a special debugging module like [debug](https://www.npmjs.com/package/debug). This module enables you to use the DEBUG environment variable to control what debug messages are sent to `console.error()`, if any. To keep your app purely asynchronous, you'd still want to pipe `console.error()` to another program. But then, you're not really going to debug in production, are you? + +#### For app activity + +If you're logging app activity (for example, tracking traffic or API calls), instead of using `console.log()`, use a logging library like [Pino](https://www.npmjs.com/package/pino), which is the fastest and most efficient option available. + +### Handle exceptions properly + +Node apps crash when they encounter an uncaught exception. Not handling exceptions and taking appropriate actions will make your Express app crash and go offline. If you follow the advice in [Ensure your app automatically restarts](#ensure-your-app-automatically-restarts) below, then your app will recover from a crash. Fortunately, Express apps typically have a short startup time. Nevertheless, you want to avoid crashing in the first place, and to do that, you need to handle exceptions properly. + +To ensure you handle all exceptions, use the following techniques: + +- [Use try-catch](#use-try-catch) +- [Use promises](#use-promises) + +Before diving into these topics, you should have a basic understanding of Node/Express error handling: using error-first callbacks, and propagating errors in middleware. Node uses an "error-first callback" convention for returning errors from asynchronous functions, where the first parameter to the callback function is the error object, followed by result data in succeeding parameters. To indicate no error, pass null as the first parameter. The callback function must correspondingly follow the error-first callback convention to meaningfully handle the error. And in Express, the best practice is to use the next() function to propagate errors through the middleware chain. + +For more on the fundamentals of error handling, see: + +- [Error Handling in Node.js](https://www.tritondatacenter.com/node-js/production/design/errors) + +#### Use try-catch + +Try-catch is a JavaScript language construct that you can use to catch exceptions in synchronous code. Use try-catch, for example, to handle JSON parsing errors as shown below. + +Here is an example of using try-catch to handle a potential process-crashing exception. +This middleware function accepts a query field parameter named "params" that is a JSON object. + +```js +app.get('/search', (req, res) => { + // Simulating async operation + setImmediate(() => { + const jsonStr = req.query.params; + try { + const jsonObj = JSON.parse(jsonStr); + res.send('Success'); + } catch (e) { + res.status(400).send('Invalid JSON string'); + } + }); +}); +``` + +However, try-catch works only for synchronous code. Because the Node platform is primarily asynchronous (particularly in a production environment), try-catch won't catch a lot of exceptions. + +#### Use promises + +When an error is thrown in an `async` function or a rejected promise is awaited inside an `async` function, those errors will be passed to the error handler as if calling `next(err)` + +```js +app.get('/', async (req, res, next) => { + const data = await userData(); // If this promise fails, it will automatically call `next(err)` to handle the error. + + res.send(data); +}); + +app.use((err, req, res, next) => { + res.status(err.status ?? 500).send({ error: err.message }); +}); +``` + +Also, you can use asynchronous functions for your middleware, and the router will handle errors if the promise fails, for example: + +```js +app.use(async (req, res, next) => { + req.locals.user = await getUser(req); + + next(); // This will be called if the promise does not throw an error. +}); +``` + +Best practice is to handle errors as close to the site as possible. So while this is now handled in the router, it’s best to catch the error in the middleware and handle it without relying on separate error-handling middleware. + +#### What not to do + +One thing you should _not_ do is to listen for the `uncaughtException` event, emitted when an exception bubbles all the way back to the event loop. Adding an event listener for `uncaughtException` will change the default behavior of the process that is encountering an exception; the process will continue to run despite the exception. This might sound like a good way of preventing your app from crashing, but continuing to run the app after an uncaught exception is a dangerous practice and is not recommended, because the state of the process becomes unreliable and unpredictable. + +Additionally, using `uncaughtException` is officially recognized as [crude](https://nodejs.org/api/process#process_event_uncaughtexception). So listening for `uncaughtException` is just a bad idea. This is why we recommend things like multiple processes and supervisors: crashing and restarting is often the most reliable way to recover from an error. + +We also don't recommend using [domains](https://nodejs.org/api/domain). It generally doesn't solve the problem and is a deprecated module. + +## Things to do in your environment / setup + +Here are some things you can do in your system environment to improve your app's performance: + +- [Set NODE_ENV to "production"](#set-node_env-to-production) +- [Ensure your app automatically restarts](#ensure-your-app-automatically-restarts) +- [Run your app in a cluster](#run-your-app-in-a-cluster) +- [Cache request results](#cache-request-results) +- [Use a load balancer](#use-a-load-balancer) +- [Use a reverse proxy](#use-a-reverse-proxy) + +### Set NODE_ENV to "production" + +The NODE_ENV environment variable specifies the environment in which an application is running (usually, development or production). One of the simplest things you can do to improve performance is to set NODE_ENV to `production`. + +Setting NODE_ENV to "production" makes Express: + +- Cache view templates. +- Cache CSS files generated from CSS extensions. +- Generate less verbose error messages. + +[Tests indicate](https://www.dynatrace.com/news/blog/the-drastic-effects-of-omitting-node-env-in-your-express-js-applications/) that just doing this can improve app performance by a factor of three! + +If you need to write environment-specific code, you can check the value of NODE_ENV with `process.env.NODE_ENV`. Be aware that checking the value of any environment variable incurs a performance penalty, and so should be done sparingly. + +In development, you typically set environment variables in your interactive shell, for example by using `export` or your `.bash_profile` file. But in general, you shouldn't do that on a production server; instead, use your OS's init system (systemd). The next section provides more details about using your init system in general, but setting `NODE_ENV` is so important for performance (and easy to do), that it's highlighted here. + +With systemd, use the `Environment` directive in your unit file. For example: + +```sh + +Environment=NODE_ENV=production +``` + +For more information, see [Using Environment Variables In systemd Units](https://www.flatcar.org/docs/latest/setup/systemd/environment-variables/). + +### Ensure your app automatically restarts + +In production, you don't want your application to be offline, ever. This means you need to make sure it restarts both if the app crashes and if the server itself crashes. Although you hope that neither of those events occurs, realistically you must account for both eventualities by: + +- Using a process manager to restart the app (and Node) when it crashes. +- Using the init system provided by your OS to restart the process manager when the OS crashes. It's also possible to use the init system without a process manager. + +Node applications crash if they encounter an uncaught exception. The foremost thing you need to do is to ensure your app is well-tested and handles all exceptions (see [handle exceptions properly](#handle-exceptions-properly) for details). But as a fail-safe, put a mechanism in place to ensure that if and when your app crashes, it will automatically restart. + +#### Use a process manager + +In development, you started your app simply from the command line with `node server.js` or something similar. But doing this in production is a recipe for disaster. If the app crashes, it will be offline until you restart it. To ensure your app restarts if it crashes, use a process manager. A process manager is a "container" for applications that facilitates deployment, provides high availability, and enables you to manage the application at runtime. + +In addition to restarting your app when it crashes, a process manager can enable you to: + +- Gain insights into runtime performance and resource consumption. +- Modify settings dynamically to improve performance. +- Control clustering (pm2). + +Historically, it was popular to use a Node.js process manager like [PM2](https://github.com/Unitech/pm2). See their documentation if you wish to do this. However, we recommend using your init system for process management. + +#### Use an init system + +The next layer of reliability is to ensure that your app restarts when the server restarts. Systems can still go down for a variety of reasons. To ensure that your app restarts if the server crashes, use the init system built into your OS. The main init system in use today is [systemd](https://wiki.debian.org/systemd). + +There are two ways to use init systems with your Express app: + +- Run your app in a process manager, and install the process manager as a service with the init system. The process manager will restart your app when the app crashes, and the init system will restart the process manager when the OS restarts. This is the recommended approach. +- Run your app (and Node) directly with the init system. This is somewhat simpler, but you don't get the additional advantages of using a process manager. + +##### Systemd + +Systemd is a Linux system and service manager. Most major Linux distributions have adopted systemd as their default init system. + +A systemd service configuration file is called a _unit file_, with a filename ending in `.service`. Here's an example unit file to manage a Node app directly. Replace the values enclosed in `` for your system and app: + +```sh +[Unit] +Description= + +[Service] +Type=simple +ExecStart=/usr/local/bin/node +WorkingDirectory= + +User=nobody +Group=nogroup + + +Environment=NODE_ENV=production + + +LimitNOFILE=infinity + + +LimitCORE=infinity + +StandardInput=null +StandardOutput=syslog +StandardError=syslog +Restart=always + +[Install] +WantedBy=multi-user.target +``` + +For more information on systemd, see the [systemd reference (man page)](http://www.freedesktop.org/software/systemd/man/systemd.unit). + +### Run your app in a cluster + +In a multi-core system, you can increase the performance of a Node app by many times by launching a cluster of processes. A cluster runs multiple instances of the app, ideally one instance on each CPU core, thereby distributing the load and tasks among the instances. + +![Balancing between application instances using the cluster API](/images/clustering.png) + +IMPORTANT: Since the app instances run as separate processes, they do not share the same memory space. That is, objects are local to each instance of the app. Therefore, you cannot maintain state in the application code. However, you can use an in-memory datastore like [Redis](http://redis.io/) to store session-related data and state. This caveat applies to essentially all forms of horizontal scaling, whether clustering with multiple processes or multiple physical servers. + +In clustered apps, worker processes can crash individually without affecting the rest of the processes. Apart from performance advantages, failure isolation is another reason to run a cluster of app processes. Whenever a worker process crashes, always make sure to log the event and spawn a new process using cluster.fork(). + +#### Using Node's cluster module + +Clustering is made possible with Node's [cluster module](https://nodejs.org/api/cluster). This enables a master process to spawn worker processes and distribute incoming connections among the workers. + +#### Using PM2 + +If you deploy your application with PM2, then you can take advantage of clustering _without_ modifying your application code. You should ensure your [application is stateless](https://pm2.keymetrics.io/docs/usage/specifics/#stateless-apps) first, meaning no local data is stored in the process (such as sessions, websocket connections and the like). + +When running an application with PM2, you can enable **cluster mode** to run it in a cluster with a number of instances of your choosing, such as the matching the number of available CPUs on the machine. You can manually change the number of processes in the cluster using the `pm2` command line tool without stopping the app. + +To enable cluster mode, start your application like so: + +```bash + +$ pm2 start npm --name my-app -i 4 -- start + +$ pm2 start npm --name my-app -i max -- start +``` + +This can also be configured within a PM2 process file (`ecosystem.config.js` or similar) by setting `exec_mode` to `cluster` and `instances` to the number of workers to start. + +Once running, the application can be scaled like so: + +```bash + +$ pm2 scale my-app +3 + +$ pm2 scale my-app 2 +``` + +For more information on clustering with PM2, see [Cluster Mode](https://pm2.keymetrics.io/docs/usage/cluster-mode/) in the PM2 documentation. + +### Cache request results + +Another strategy to improve the performance in production is to cache the result of requests, so that your app does not repeat the operation to serve the same request repeatedly. + +Use a caching server like [Varnish](https://www.varnish-cache.org/) or [Nginx](https://blog.nginx.org/blog/nginx-caching-guide) (see also [Nginx Caching](https://serversforhackers.com/nginx-caching/)) to greatly improve the speed and performance of your app. + +### Use a load balancer + +No matter how optimized an app is, a single instance can handle only a limited amount of load and traffic. One way to scale an app is to run multiple instances of it and distribute the traffic via a load balancer. Setting up a load balancer can improve your app's performance and speed, and enable it to scale more than is possible with a single instance. + +A load balancer is usually a reverse proxy that orchestrates traffic to and from multiple application instances and servers. You can easily set up a load balancer for your app by using [Nginx](https://nginx.org/en/docs/http/load_balancing) or [HAProxy](https://www.digitalocean.com/community/tutorials/an-introduction-to-haproxy-and-load-balancing-concepts). + +With load balancing, you might have to ensure that requests that are associated with a particular session ID connect to the process that originated them. This is known as _session affinity_, or _sticky sessions_, and may be addressed by the suggestion above to use a data store such as Redis for session data (depending on your application). For a discussion, see [Using multiple nodes](https://socket.io/docs/v4/using-multiple-nodes/). + +### Use a reverse proxy + +A reverse proxy sits in front of a web app and performs supporting operations on the requests, apart from directing requests to the app. It can handle error pages, compression, caching, serving files, and load balancing among other things. + +Handing over tasks that do not require knowledge of application state to a reverse proxy frees up Express to perform specialized application tasks. For this reason, it is recommended to run Express behind a reverse proxy like [Nginx](https://www.nginx.org/) or [HAProxy](https://www.haproxy.org/) in production. diff --git a/src/content/pages/zh-tw/advanced/best-practice-security.mdx b/src/content/pages/zh-tw/advanced/best-practice-security.mdx new file mode 100644 index 0000000000..fa7b7622bb --- /dev/null +++ b/src/content/pages/zh-tw/advanced/best-practice-security.mdx @@ -0,0 +1,276 @@ +--- +title: "Production Best Practices: Security" +description: Discover crucial security best practices for Express apps in production, including using TLS, input validation, secure cookies, and preventing vulnerabilities. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +The term *"production"* refers to the stage in the software lifecycle when an application or API is generally available to its end-users or consumers. In contrast, in the *"development"* stage, you're still actively writing and testing code, and the application is not open to external access. The corresponding system environments are known as *production* and *development* environments, respectively. + +Development and production environments are usually set up differently and have vastly different requirements. What's fine in development may not be acceptable in production. For example, in a development environment you may want verbose logging of errors for debugging, while the same behavior can become a security concern in a production environment. And in development, you don't need to worry about scalability, reliability, and performance, while those concerns become critical in production. + + + +If you believe you have discovered a security vulnerability in Express, please see Security +Policies and Procedures. + + + +Security best practices for Express applications in production include: + +* [Production Best Practices: Security](#production-best-practices-security) + * [Overview](#overview) + * [Don't use deprecated or vulnerable versions of Express](#dont-use-deprecated-or-vulnerable-versions-of-express) + * [Use TLS](#use-tls) + * [Do not trust user input](#do-not-trust-user-input) + * [Prevent open redirects](#prevent-open-redirects) + * [Use Helmet](#use-helmet) + * [Reduce fingerprinting](#reduce-fingerprinting) + * [Use cookies securely](#use-cookies-securely) + * [Don't use the default session cookie name](#dont-use-the-default-session-cookie-name) + * [Set cookie security options](#set-cookie-security-options) + * [Prevent brute-force attacks against authorization](#prevent-brute-force-attacks-against-authorization) + * [Ensure your dependencies are secure](#ensure-your-dependencies-are-secure) + * [Avoid other known vulnerabilities](#avoid-other-known-vulnerabilities) + * [Additional considerations](#additional-considerations) + +## Don't use deprecated or vulnerable versions of Express + +Express 2.x and 3.x are no longer maintained. Security and performance issues in these versions won't be fixed. Do not use them! If you haven't moved to version 4, follow the [migration guide](/en/guide/migrating-4) or consider [Commercial Support Options](/en/support#commercial-support-options). + +Also ensure you are not using any of the vulnerable Express versions listed on the [Security updates page](/en/advanced/security-updates). If you are, update to one of the stable releases, preferably the latest. + +## Use TLS + +If your app deals with or transmits sensitive data, use [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) to secure the connection and the data. This technology encrypts data before it is sent from the client to the server, thus preventing some common (and easy) hacks. Although Ajax and POST requests might not be visibly obvious and seem "hidden" in browsers, their network traffic is vulnerable to [packet sniffing](https://en.wikipedia.org/wiki/Packet_analyzer) and [man-in-the-middle attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). + +You may be familiar with Secure Socket Layer (SSL) encryption. [TLS is simply the next progression of SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). In other words, if you were using SSL before, consider upgrading to TLS. In general, we recommend Nginx to handle TLS. For a good reference to configure TLS on Nginx (and other servers), see [Recommended Server Configurations (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). + +Also, a handy tool to get a free TLS certificate is [Let's Encrypt](https://letsencrypt.org/about/), a free, automated, and open certificate authority (CA) provided by the [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). + +## Do not trust user input + +For web applications, one of the most critical security requirements is proper user input validation and handling. This comes in many forms and we will not cover all of them here. +Ultimately, the responsibility for validating and correctly handling the types of user input your application accepts is yours. + +### Prevent open redirects + +An example of potentially dangerous user input is an *open redirect*, where an application accepts a URL as user input (often in the URL query, for example `?url=https://example.com`) and uses `res.redirect` to set the `location` header and +return a 3xx status. + +An application must validate that it supports redirecting to the incoming URL to avoid sending users to malicious links such as phishing websites, among other risks. + +Here is an example of checking URLs before using `res.redirect` or `res.location`: + +```js +app.use((req, res) => { + try { + if (new Url(req.query.url).host !== 'example.com') { + return res.status(400).end(`Unsupported redirect to host: ${req.query.url}`); + } + } catch (e) { + return res.status(400).end(`Invalid url: ${req.query.url}`); + } + res.redirect(req.query.url); +}); +``` + +## Use Helmet + +[Helmet][helmet] can help protect your app from some well-known web vulnerabilities by setting HTTP headers appropriately. + +Helmet is a middleware function that sets security-related HTTP response headers. Helmet sets the following headers by default: + +* `Content-Security-Policy`: A powerful allow-list of what can happen on your page which mitigates many attacks +* `Cross-Origin-Opener-Policy`: Helps process-isolate your page +* `Cross-Origin-Resource-Policy`: Blocks others from loading your resources cross-origin +* `Origin-Agent-Cluster`: Changes process isolation to be origin-based +* `Referrer-Policy`: Controls the [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) header +* `Strict-Transport-Security`: Tells browsers to prefer HTTPS +* `X-Content-Type-Options`: Avoids [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +* `X-DNS-Prefetch-Control`: Controls DNS prefetching +* `X-Download-Options`: Forces downloads to be saved (Internet Explorer only) +* `X-Frame-Options`: Legacy header that mitigates [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) attacks +* `X-Permitted-Cross-Domain-Policies`: Controls cross-domain behavior for Adobe products, like Acrobat +* `X-Powered-By`: Info about the web server. Removed because it could be used in simple attacks +* `X-XSS-Protection`: Legacy header that tries to mitigate [XSS attacks](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), but makes things worse, so Helmet disables it + +Each header can be configured or disabled. To read more about it please go to [its documentation website][helmet]. + +Install Helmet like any other module: + +```bash +$ npm install helmet +``` + +Then to use it in your code: + +```js +// ... + +const helmet = require('helmet'); +app.use(helmet()); + +// ... +``` + +## Reduce fingerprinting + +It can help to provide an extra layer of security to reduce the ability of attackers to determine +the software that a server uses, known as "fingerprinting." Though not a security issue itself, +reducing the ability to fingerprint an application improves its overall security posture. +Server software can be fingerprinted by quirks in how it responds to specific requests, for example in +the HTTP response headers. + +By default, Express sends the `X-Powered-By` response header that you can +disable using the `app.disable()` method: + +```js +app.disable('x-powered-by'); +``` + + + +Disabling the `X-Powered-By header` does not prevent a sophisticated attacker from determining +that an app is running Express. It may discourage a casual exploit, but there are other ways to +determine an app is running Express. + + + +Express also sends its own formatted "404 Not Found" messages and formatter error +response messages. These can be changed by +[adding your own not found handler](/en/starter/faq#how-do-i-handle-404-responses) +and +[writing your own error handler](/en/guide/error-handling#writing-error-handlers): + +```js +// last app.use calls right before app.listen(): + +// custom 404 +app.use((req, res, next) => { + res.status(404).send("Sorry can't find that!"); +}); + +// custom error handler +app.use((err, req, res, next) => { + console.error(err.stack); + res.status(500).send('Something broke!'); +}); +``` + +## Use cookies securely + +To ensure cookies don't open your app to exploits, don't use the default session cookie name and set cookie security options appropriately. + +There are two main middleware cookie session modules: + +* [express-session](https://www.npmjs.com/package/express-session) that replaces `express.session` middleware built-in to Express 3.x. +* [cookie-session](https://www.npmjs.com/package/cookie-session) that replaces `express.cookieSession` middleware built-in to Express 3.x. + +The main difference between these two modules is how they save cookie session data. The [express-session](https://www.npmjs.com/package/express-session) middleware stores session data on the server; it only saves the session ID in the cookie itself, not session data. By default, it uses in-memory storage and is not designed for a production environment. In production, you'll need to set up a scalable session-store; see the list of [compatible session stores](https://github.com/expressjs/session#compatible-session-stores). + +In contrast, [cookie-session](https://www.npmjs.com/package/cookie-session) middleware implements cookie-backed storage: it serializes the entire session to the cookie, rather than just a session key. Only use it when session data is relatively small and easily encoded as primitive values (rather than objects). Although browsers are supposed to support at least 4096 bytes per cookie, to ensure you don't exceed the limit, don't exceed a size of 4093 bytes per domain. Also, be aware that the cookie data will be visible to the client, so if there is any reason to keep it secure or obscure, then `express-session` may be a better choice. + +### Don't use the default session cookie name + +Using the default session cookie name can open your app to attacks. The security issue posed is similar to `X-Powered-By`: a potential attacker can use it to fingerprint the server and target attacks accordingly. + +To avoid this problem, use generic cookie names; for example using [express-session](https://www.npmjs.com/package/express-session) middleware: + +```js +const session = require('express-session'); +app.set('trust proxy', 1); // trust first proxy +app.use( + session({ + secret: 's3Cur3', + name: 'sessionId', + }) +); +``` + +### Set cookie security options + +Set the following cookie options to enhance security: + +* `secure` - Ensures the browser only sends the cookie over HTTPS. +* `httpOnly` - Ensures the cookie is sent only over HTTP(S), not client JavaScript, helping to protect against cross-site scripting attacks. +* `domain` - indicates the domain of the cookie; use it to compare against the domain of the server in which the URL is being requested. If they match, then check the path attribute next. +* `path` - indicates the path of the cookie; use it to compare against the request path. If this and domain match, then send the cookie in the request. +* `expires` - use to set expiration date for persistent cookies. + +Here is an example using [cookie-session](https://www.npmjs.com/package/cookie-session) middleware: + +```js +const session = require('cookie-session'); +const express = require('express'); +const app = express(); + +const expiryDate = new Date(Date.now() + 60 * 60 * 1000); // 1 hour +app.use( + session({ + name: 'session', + keys: ['key1', 'key2'], + cookie: { + secure: true, + httpOnly: true, + domain: 'example.com', + path: 'foo/bar', + expires: expiryDate, + }, + }) +); +``` + +## Prevent brute-force attacks against authorization + +Make sure login endpoints are protected to make private data more secure. + +A simple and powerful technique is to block authorization attempts using two metrics: + +1. The number of consecutive failed attempts by the same user name and IP address. +2. The number of failed attempts from an IP address over some long period of time. For example, block an IP address if it makes 100 failed attempts in one day. + +[rate-limiter-flexible](https://github.com/animir/node-rate-limiter-flexible) package provides tools to make this technique easy and fast. You can find [an example of brute-force protection in the documentation](https://github.com/animir/node-rate-limiter-flexible/wiki/Overall-example#login-endpoint-protection) + +## Ensure your dependencies are secure + +Using npm to manage your application's dependencies is powerful and convenient. But the packages that you use may contain critical security vulnerabilities that could also affect your application. The security of your app is only as strong as the "weakest link" in your dependencies. + +Since npm@6, npm automatically reviews every install request. Also, you can use `npm audit` to analyze your dependency tree. + +```bash +$ npm audit +``` + +If you want to stay more secure, consider [Snyk](https://snyk.io/). + +Snyk offers both a [command-line tool](https://www.npmjs.com/package/snyk) and a [Github integration](https://snyk.io/docs/github) that checks your application against [Snyk's open source vulnerability database](https://snyk.io/vuln/) for any known vulnerabilities in your dependencies. Install the CLI as follows: + +```bash +$ npm install -g snyk +$ cd your-app +``` + +Use this command to test your application for vulnerabilities: + +```bash +$ snyk test +``` + +### Avoid other known vulnerabilities + +Keep an eye out for [Node Security Project](https://npmjs.com/advisories) or [Snyk](https://snyk.io/vuln/) advisories that may affect Express or other modules that your app uses. In general, these databases are excellent resources for knowledge and tools about Node security. + +Finally, Express apps—like any other web apps—can be vulnerable to a variety of web-based attacks. Familiarize yourself with known [web vulnerabilities](https://www.owasp.org/www-project-top-ten/) and take precautions to avoid them. + +## Additional considerations + +Here are some further recommendations from the excellent [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/). Refer to that blog post for all the details on these recommendations: + +* Always filter and sanitize user input to protect against cross-site scripting (XSS) and command injection attacks. +* Defend against SQL injection attacks by using parameterized queries or prepared statements. +* Use the open-source [sqlmap](http://sqlmap.org/) tool to detect SQL injection vulnerabilities in your app. +* Use the [nmap](https://nmap.org/) and [sslyze](https://github.com/nabla-c0d3/sslyze) tools to test the configuration of your SSL ciphers, keys, and renegotiation as well as the validity of your certificate. +* Use [safe-regex](https://www.npmjs.com/package/safe-regex) to ensure your regular expressions are not susceptible to [regular expression denial of service](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) attacks. + +[helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/zh-tw/advanced/healthcheck-graceful-shutdown.md b/src/content/pages/zh-tw/advanced/healthcheck-graceful-shutdown.md new file mode 100644 index 0000000000..c060e58605 --- /dev/null +++ b/src/content/pages/zh-tw/advanced/healthcheck-graceful-shutdown.md @@ -0,0 +1,28 @@ +--- +title: Health Checks and Graceful Shutdown +description: Learn how to implement health checks and graceful shutdown in Express apps to enhance reliability, manage deployments, and integrate with load balancers like Kubernetes. +--- + +## Graceful shutdown + +When you deploy a new version of your application, you must replace the previous version. The process manager you're using will first send a SIGTERM signal to the application to notify it that it will be killed. Once the application gets this signal, it should stop accepting new requests, finish all the ongoing requests, clean up the resources it used, including database connections and file locks then exit. + +### Example + +```js +const server = app.listen(port); + +process.on('SIGTERM', () => { + debug('SIGTERM signal received: closing HTTP server'); + server.close(() => { + debug('HTTP server closed'); + }); +}); +``` + +## Health checks + +A load balancer uses health checks to determine if an application instance is healthy and can accept requests. For example, [Kubernetes has two health checks](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/): + +- `liveness`, that determines when to restart a container. +- `readiness`, that determines when a container is ready to start accepting traffic. When a pod is not ready, it is removed from the service load balancers. diff --git a/src/content/pages/zh-tw/advanced/security-updates.mdx b/src/content/pages/zh-tw/advanced/security-updates.mdx new file mode 100644 index 0000000000..dfed519ec6 --- /dev/null +++ b/src/content/pages/zh-tw/advanced/security-updates.mdx @@ -0,0 +1,87 @@ +--- +title: Security updates +description: Review the latest security updates and patches for Express.js, including detailed vulnerability lists for different versions to help maintain a secure application. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + + + +Node.js vulnerabilities directly affect Express. Therefore, keep a watch on Node.js +vulnerabilities and make sure you are using the latest +stable version of Node.js. + + + +The list below enumerates the Express vulnerabilities that were fixed in the specified version update. + + + +If you believe you have discovered a security vulnerability in Express, please see Security +Policies and Procedures. + + + +## 4.x + +* 4.21.2 + * The dependency `path-to-regexp` has been updated to address a [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +* 4.21.1 + * The dependency `cookie` has been updated to address a [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), This may affect your application if you use `res.cookie`. +* 4.20.0 + * Fixed XSS vulnerability in `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + * The dependency `serve-static` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). + * The dependency `send` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + * The dependency `path-to-regexp` has been updated to address a [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + * The dependency `body-parser` has been updated to addres a [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), This may affect your application if you had url enconding activated. +* 4.19.0, 4.19.1 + * Fixed open redirect vulnerability in `res.location` and `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +* 4.17.3 + * The dependency `qs` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). This may affect your application if the following APIs are used: `req.query`, `req.body`, `req.param`. +* 4.16.0 + * The dependency `forwarded` has been updated to address a [vulnerability](https://npmjs.com/advisories/527). This may affect your application if the following APIs are used: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + * The dependency `mime` has been updated to address a [vulnerability](https://npmjs.com/advisories/535), but this issue does not impact Express. + * The dependency `send` has been updated to provide a protection against a [Node.js 8.5.0 vulnerability](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). This only impacts running Express on the specific Node.js version 8.5.0. +* 4.15.5 + * The dependency `debug` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:debug:20170905), but this issue does not impact Express. + * The dependency `fresh` has been updated to address a [vulnerability](https://npmjs.com/advisories/526). This will affect your application if the following APIs are used: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. +* 4.15.3 + * The dependency `ms` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:ms:20170412). This may affect your application if untrusted string input is passed to the `maxAge` option in the following APIs: `express.static`, `res.sendfile`, and `res.sendFile`. +* 4.15.2 + * The dependency `qs` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:qs:20170213), but this issue does not impact Express. Updating to 4.15.2 is a good practice, but not required to address the vulnerability. +* 4.11.1 + * Fixed root path disclosure vulnerability in `express.static`, `res.sendfile`, and `res.sendFile` +* 4.10.7 + * Fixed open redirect vulnerability in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 4.8.8 + * Fixed directory traversal vulnerabilities in `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +* 4.8.4 + * Node.js 0.10 can leak `fd`s in certain situations that affect `express.static` and `res.sendfile`. Malicious requests could cause `fd`s to leak and eventually lead to `EMFILE` errors and server unresponsiveness. +* 4.8.0 + * Sparse arrays that have extremely high indexes in the query string could cause the process to run out of memory and crash the server. + * Extremely nested query string objects could cause the process to block and make the server unresponsive temporarily. + +## 3.x + + +**Express 3.x IS END-OF-LIFE AND NO LONGER MAINTAINED** + +Known and unknown security and performance issues in 3.x have not been addressed since the last update (1 August, 2015). It is highly recommended to use the latest version of Express. + +If you are unable to upgrade past 3.x, please consider [Commercial Support Options](/en/support#commercial-support-options). + + + +* 3.19.1 + * Fixed root path disclosure vulnerability in `express.static`, `res.sendfile`, and `res.sendFile` +* 3.19.0 + * Fixed open redirect vulnerability in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +* 3.16.10 + * Fixed directory traversal vulnerabilities in `express.static`. +* 3.16.6 + * Node.js 0.10 can leak `fd`s in certain situations that affect `express.static` and `res.sendfile`. Malicious requests could cause `fd`s to leak and eventually lead to `EMFILE` errors and server unresponsiveness. +* 3.16.0 + * Sparse arrays that have extremely high indexes in query string could cause the process to run out of memory and crash the server. + * Extremely nested query string objects could cause the process to block and make the server unresponsive temporarily. +* 3.3.0 + * The 404 response of an unsupported method override attempt was susceptible to cross-site scripting attacks. diff --git a/src/content/pages/zh-tw/guide/database-integration.mdx b/src/content/pages/zh-tw/guide/database-integration.mdx new file mode 100644 index 0000000000..9a97d66c47 --- /dev/null +++ b/src/content/pages/zh-tw/guide/database-integration.mdx @@ -0,0 +1,503 @@ +--- +title: Database integration +description: Discover how to integrate various databases with Express.js applications, including setup examples for MongoDB, MySQL, PostgreSQL, and more. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Adding the capability to connect databases to Express apps is just a matter of loading an appropriate Node.js driver for the database in your app. This document briefly explains how to add and use some of the most popular Node.js modules for database systems in your Express app: + +* [Cassandra](#cassandra) +* [Couchbase](#couchbase) +* [CouchDB](#couchdb) +* [LevelDB](#leveldb) +* [MySQL](#mysql) +* [MongoDB](#mongodb) +* [Neo4j](#neo4j) +* [Oracle](#oracle) +* [PostgreSQL](#postgresql) +* [Redis](#redis) +* [SQL Server](#sql-server) +* [SQLite](#sqlite) +* [Elasticsearch](#elasticsearch) + + + +These database drivers are among many that are available. For other options, search on the +[npm](https://www.npmjs.com/) site. + + + +## Cassandra + +**Module**: [cassandra-driver](https://github.com/datastax/nodejs-driver) + +### Installation + +```bash +$ npm install cassandra-driver +``` + +### Example + +```js +const cassandra = require('cassandra-driver'); +const client = new cassandra.Client({ contactPoints: ['localhost'] }); + +client.execute('select key from system.local', (err, result) => { + if (err) throw err; + console.log(result.rows[0]); +}); +``` + +## Couchbase + +**Module**: [couchnode](https://github.com/couchbase/couchnode) + +### Installation + +```bash +$ npm install couchbase +``` + +### Example + +```js +const couchbase = require('couchbase'); +const bucket = new couchbase.Cluster('http://localhost:8091').openBucket('bucketName'); + +// add a document to a bucket +bucket.insert('document-key', { name: 'Matt', shoeSize: 13 }, (err, result) => { + if (err) { + console.log(err); + } else { + console.log(result); + } +}); + +// get all documents with shoe size 13 +const n1ql = 'SELECT d.* FROM `bucketName` d WHERE shoeSize = $1'; +const query = N1qlQuery.fromString(n1ql); +bucket.query(query, [13], (err, result) => { + if (err) { + console.log(err); + } else { + console.log(result); + } +}); +``` + +## CouchDB + +**Module**: [nano](https://github.com/dscape/nano) + +### Installation + +```bash +$ npm install nano +``` + +### Example + +```js +const nano = require('nano')('http://localhost:5984'); +nano.db.create('books'); +const books = nano.db.use('books'); + +// Insert a book document in the books database +books.insert({ name: 'The Art of war' }, null, (err, body) => { + if (err) { + console.log(err); + } else { + console.log(body); + } +}); + +// Get a list of all books +books.list((err, body) => { + if (err) { + console.log(err); + } else { + console.log(body.rows); + } +}); +``` + +## LevelDB + +**Module**: [levelup](https://github.com/rvagg/node-levelup) + +### Installation + +```bash +$ npm install level levelup leveldown +``` + +### Example + +```js +const levelup = require('levelup'); +const db = levelup('./mydb'); + +db.put('name', 'LevelUP', (err) => { + if (err) return console.log('Ooops!', err); + + db.get('name', (err, value) => { + if (err) return console.log('Ooops!', err); + + console.log(`name=${value}`); + }); +}); +``` + +## MySQL + +**Module**: [mysql](https://github.com/felixge/node-mysql/) + +### Installation + +```bash +$ npm install mysql +``` + +### Example + +```js +const mysql = require('mysql'); +const connection = mysql.createConnection({ + host: 'localhost', + user: 'dbuser', + password: 's3kreee7', + database: 'my_db', +}); + +connection.connect(); + +connection.query('SELECT 1 + 1 AS solution', (err, rows, fields) => { + if (err) throw err; + + console.log('The solution is: ', rows[0].solution); +}); + +connection.end(); +``` + +## MongoDB + +**Module**: [mongodb](https://github.com/mongodb/node-mongodb-native) + +### Installation + +```bash +$ npm install mongodb +``` + +### Example (v2.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { + if (err) throw err; + + db.collection('mammals') + .find() + .toArray((err, result) => { + if (err) throw err; + + console.log(result); + }); +}); +``` + +### Example (v3.*) + +```js +const MongoClient = require('mongodb').MongoClient; + +MongoClient.connect('mongodb://localhost:27017/animals', (err, client) => { + if (err) throw err; + + const db = client.db('animals'); + + db.collection('mammals') + .find() + .toArray((err, result) => { + if (err) throw err; + + console.log(result); + }); +}); +``` + +If you want an object model driver for MongoDB, look at [Mongoose](https://github.com/LearnBoost/mongoose). + +## Neo4j + +**Module**: [neo4j-driver](https://github.com/neo4j/neo4j-javascript-driver) + +### Installation + +```bash +$ npm install neo4j-driver +``` + +### Example + +```js +const neo4j = require('neo4j-driver'); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth.basic('neo4j', 'letmein')); + +const session = driver.session(); + +session.readTransaction((tx) => { + return tx + .run('MATCH (n) RETURN count(n) AS count') + .then((res) => { + console.log(res.records[0].get('count')); + }) + .catch((error) => { + console.log(error); + }); +}); +``` + +## Oracle + +**Module**: [oracledb](https://github.com/oracle/node-oracledb) + +### Installation + +NOTE: [See installation prerequisites](https://github.com/oracle/node-oracledb#-installation). + +```bash +$ npm install oracledb +``` + +### Example + +```js +const oracledb = require('oracledb'); +const config = { + user: '', + password: '', + connectString: 'localhost:1521/orcl', +}; + +async function getEmployee(empId) { + let conn; + + try { + conn = await oracledb.getConnection(config); + + const result = await conn.execute('select * from employees where employee_id = :id', [empId]); + + console.log(result.rows[0]); + } catch (err) { + console.log('Ouch!', err); + } finally { + if (conn) { + // conn assignment worked, need to close + await conn.close(); + } + } +} + +getEmployee(101); +``` + +## PostgreSQL + +**Module**: [pg-promise](https://github.com/vitaly-t/pg-promise) + +### Installation + +```bash +$ npm install pg-promise +``` + +### Example + +```js +const pgp = require('pg-promise')(/* options */); +const db = pgp('postgres://username:password@host:port/database'); + +db.one('SELECT $1 AS value', 123) + .then((data) => { + console.log('DATA:', data.value); + }) + .catch((error) => { + console.log('ERROR:', error); + }); +``` + +## Redis + +**Module**: [redis](https://github.com/mranney/node_redis) + +### Installation + +```bash +$ npm install redis +``` + +### Example + +```js +const redis = require('redis'); +const client = redis.createClient(); + +client.on('error', (err) => { + console.log(`Error ${err}`); +}); + +client.set('string key', 'string val', redis.print); +client.hset('hash key', 'hashtest 1', 'some value', redis.print); +client.hset(['hash key', 'hashtest 2', 'some other value'], redis.print); + +client.hkeys('hash key', (err, replies) => { + console.log(`${replies.length} replies:`); + + replies.forEach((reply, i) => { + console.log(` ${i}: ${reply}`); + }); + + client.quit(); +}); +``` + +## SQL Server + +**Module**: [tedious](https://github.com/tediousjs/tedious) + +### Installation + +```bash +$ npm install tedious +``` + +### Example + +```js +const Connection = require('tedious').Connection; +const Request = require('tedious').Request; + +const config = { + server: 'localhost', + authentication: { + type: 'default', + options: { + userName: 'your_username', // update me + password: 'your_password', // update me + }, + }, +}; + +const connection = new Connection(config); + +connection.on('connect', (err) => { + if (err) { + console.log(err); + } else { + executeStatement(); + } +}); + +function executeStatement() { + request = new Request("select 123, 'hello world'", (err, rowCount) => { + if (err) { + console.log(err); + } else { + console.log(`${rowCount} rows`); + } + connection.close(); + }); + + request.on('row', (columns) => { + columns.forEach((column) => { + if (column.value === null) { + console.log('NULL'); + } else { + console.log(column.value); + } + }); + }); + + connection.execSql(request); +} +``` + +## SQLite + +**Module**: [sqlite3](https://github.com/mapbox/node-sqlite3) + +### Installation + +```bash +$ npm install sqlite3 +``` + +### Example + +```js +const sqlite3 = require('sqlite3').verbose(); +const db = new sqlite3.Database(':memory:'); + +db.serialize(() => { + db.run('CREATE TABLE lorem (info TEXT)'); + const stmt = db.prepare('INSERT INTO lorem VALUES (?)'); + + for (let i = 0; i < 10; i++) { + stmt.run(`Ipsum ${i}`); + } + + stmt.finalize(); + + db.each('SELECT rowid AS id, info FROM lorem', (err, row) => { + console.log(`${row.id}: ${row.info}`); + }); +}); + +db.close(); +``` + +## Elasticsearch + +**Module**: [elasticsearch](https://github.com/elastic/elasticsearch-js) + +### Installation + +```bash +$ npm install elasticsearch +``` + +### Example + +```js +const elasticsearch = require('elasticsearch'); +const client = elasticsearch.Client({ + host: 'localhost:9200', +}); + +client + .search({ + index: 'books', + type: 'book', + body: { + query: { + multi_match: { + query: 'express js', + fields: ['title', 'description'], + }, + }, + }, + }) + .then( + (response) => { + const hits = response.hits.hits; + }, + (error) => { + console.trace(error.message); + } + ); +``` diff --git a/src/content/pages/zh-tw/guide/migrating-4.mdx b/src/content/pages/zh-tw/guide/migrating-4.mdx new file mode 100644 index 0000000000..619682818a --- /dev/null +++ b/src/content/pages/zh-tw/guide/migrating-4.mdx @@ -0,0 +1,662 @@ +--- +title: Moving to Express 4 +description: A guide to migrating your Express.js applications from version 3 to 4, covering changes in middleware, routing, and how to update your codebase effectively. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express 4 is a breaking change from Express 3. That means an existing Express 3 app will *not* work if you update the Express version in its dependencies. + +This article covers: + + + +## Changes in Express 4 + +There are several significant changes in Express 4: + + + +See also: + +* [New features in 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +* [Migrating from 3.x to 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) + +### Changes to Express core and middleware system + +Express 4 no longer depends on Connect, and removes all built-in +middleware from its core, except for the `express.static` function. This means that +Express is now an independent routing and middleware web framework, and +Express versioning and releases are not affected by middleware updates. + +Without built-in middleware, you must explicitly add all the +middleware that is required to run your app. Simply follow these steps: + +1. Install the module: `npm install --save ` +2. In your app, require the module: `require('module-name')` +3. Use the module according to its documentation: `app.use( ... )` + +The following table lists Express 3 middleware and their counterparts in Express 4. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Express 3Express 4
+ express.bodyParser + + body-parser + + multer +
+ express.compress + + compression +
+ express.cookieSession + + cookie-session +
+ express.cookieParser + + cookie-parser +
+ express.logger + + morgan +
+ express.session + + express-session +
+ express.favicon + + serve-favicon +
+ express.responseTime + + response-time +
+ express.errorHandler + + errorhandler +
+ express.methodOverride + + method-override +
+ express.timeout + + connect-timeout +
+ express.vhost + + vhost +
+ express.csrf + + csurf +
+ express.directory + + serve-index +
+ express.static + + serve-static +
+ +Here is the [complete list](https://github.com/senchalabs/connect#middleware) of Express 4 middleware. + +In most cases, you can simply replace the old version 3 middleware with +its Express 4 counterpart. For details, see the module documentation in +GitHub. + +#### `app.use` accepts parameters + +In version 4 you can use a variable parameter to define the path where middleware functions are loaded, then read the value of the parameter from the route handler. +For example: + +```js +app.use('/book/:id', (req, res, next) => { + console.log('ID:', req.params.id); + next(); +}); +``` + +### The routing system + +Apps now implicitly load routing middleware, so you no longer have to +worry about the order in which middleware is loaded with respect to +the `router` middleware. + +The way you define routes is unchanged, but the routing system has two +new features to help organize your routes: + +* A new method, `app.route()`, to create chainable route handlers for a route path. +* A new class, `express.Router`, to create modular mountable route handlers. + +#### `app.route()` method + +The new `app.route()` method enables you to create chainable route handlers +for a route path. Because the path is specified in a single location, creating modular routes is helpful, as is reducing redundancy and typos. For more +information about routes, see [`Router()` documentation](/en/4x/api#router). + +Here is an example of chained route handlers that are defined by using the `app.route()` function. + +```js +app + .route('/book') + .get((req, res) => { + res.send('Get a random book'); + }) + .post((req, res) => { + res.send('Add a book'); + }) + .put((req, res) => { + res.send('Update the book'); + }); +``` + +#### `express.Router` class + +The other feature that helps to organize routes is a new class, +`express.Router`, that you can use to create modular mountable +route handlers. A `Router` instance is a complete middleware and +routing system; for this reason it is often referred to as a "mini-app". + +The following example creates a router as a module, loads middleware in +it, defines some routes, and mounts it on a path on the main app. + +For example, create a router file named `birds.js` in the app directory, +with the following content: + +```js +var express = require('express'); +var router = express.Router(); + +// middleware specific to this router +router.use((req, res, next) => { + console.log('Time: ', Date.now()); + next(); +}); +// define the home page route +router.get('/', (req, res) => { + res.send('Birds home page'); +}); +// define the about route +router.get('/about', (req, res) => { + res.send('About birds'); +}); + +module.exports = router; +``` + +Then, load the router module in the app: + +```js +var birds = require('./birds'); + +// ... + +app.use('/birds', birds); +``` + +The app will now be able to handle requests to the `/birds` and +`/birds/about` paths, and will call the `timeLog` +middleware that is specific to the route. + +### Other changes + +The following table lists other small but important changes in Express 4: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ObjectDescription
Node.jsExpress 4 requires Node.js 0.10.x or later and has dropped support for Node.js 0.8.x.
`http.createServer()` + The `http` module is no longer needed, unless you need to directly work with it + (socket.io/SPDY/HTTPS). The app can be started by using the `app.listen()` function. +
`app.configure()` + The `app.configure()` function has been removed. Use the `process.env.NODE_ENV` or + `app.get('env')` function to detect the environment and configure the app accordingly. +
`json spaces` + The `json spaces` application property is disabled by default in Express 4. +
`req.accepted()` + Use `req.accepts()`, `req.acceptsEncodings()`, `req.acceptsCharsets()`, and + `req.acceptsLanguages()`. +
`res.location()`No longer resolves relative URLs.
`req.params`Was an array; now an object.
`res.locals`Was a function; now an object.
`res.headerSent`Changed to `res.headersSent`.
`app.route`Now available as `app.mountpath`.
`res.on('header')`Removed.
`res.charset`Removed.
`res.setHeader('Set-Cookie', val)` + Functionality is now limited to setting the basic cookie value. Use `res.cookie()` for added + functionality. +
+ +## Example app migration + +Here is an example of migrating an Express 3 application to Express 4. +The files of interest are `app.js` and `package.json`. + +### Version 3 app + +#### `app.js` + +Consider an Express v.3 application with the following `app.js` file: + +```js +var express = require('express'); +var routes = require('./routes'); +var user = require('./routes/user'); +var http = require('http'); +var path = require('path'); + +var app = express(); + +// all environments +app.set('port', process.env.PORT || 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(express.favicon()); +app.use(express.logger('dev')); +app.use(express.methodOverride()); +app.use(express.session({ secret: 'your secret here' })); +app.use(express.bodyParser()); +app.use(app.router); +app.use(express.static(path.join(__dirname, 'public'))); + +// development only +if (app.get('env') === 'development') { + app.use(express.errorHandler()); +} + +app.get('/', routes.index); +app.get('/users', user.list); + +http.createServer(app).listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + +#### `package.json` + +The accompanying version 3 `package.json` file might look +something like this: + +```json +{ + "name": "application-name", + "version": "0.0.1", + "private": true, + "scripts": { + "start": "node app.js" + }, + "dependencies": { + "express": "3.12.0", + "pug": "*" + } +} +``` + +### Process + +Begin the migration process by installing the required middleware for the +Express 4 app and updating Express and Pug to their respective latest +version with the following command: + +```bash +$ npm install serve-favicon morgan method-override express-session body-parser multer errorhandler express@latest pug@latest --save +``` + +Make the following changes to `app.js`: + +1. The built-in Express middleware functions `express.favicon`, + `express.logger`, `express.methodOverride`, + `express.session`, `express.bodyParser` and + `express.errorHandler` are no longer available on the + `express` object. You must install their alternatives + manually and load them in the app. + +2. You no longer need to load the `app.router` function. + It is not a valid Express 4 app object, so remove the + `app.use(app.router);` code. + +3. Make sure that the middleware functions are loaded in the correct order - load `errorHandler` after loading the app routes. + +### Version 4 app + +#### `package.json` + +Running the above `npm` command will update `package.json` as follows: + +```json +{ + "name": "application-name", + "version": "0.0.1", + "private": true, + "scripts": { + "start": "node app.js" + }, + "dependencies": { + "body-parser": "^1.5.2", + "errorhandler": "^1.1.1", + "express": "^4.8.0", + "express-session": "^1.7.2", + "pug": "^2.0.0", + "method-override": "^2.1.2", + "morgan": "^1.2.2", + "multer": "^0.1.3", + "serve-favicon": "^2.0.1" + } +} +``` + +#### `app.js` + +Then, remove invalid code, load the required middleware, and make other +changes as necessary. The `app.js` file will look like this: + +```js +var http = require('http'); +var express = require('express'); +var routes = require('./routes'); +var user = require('./routes/user'); +var path = require('path'); + +var favicon = require('serve-favicon'); +var logger = require('morgan'); +var methodOverride = require('method-override'); +var session = require('express-session'); +var bodyParser = require('body-parser'); +var multer = require('multer'); +var errorHandler = require('errorhandler'); + +var app = express(); + +// all environments +app.set('port', process.env.PORT || 3000); +app.set('views', path.join(__dirname, 'views')); +app.set('view engine', 'pug'); +app.use(favicon(path.join(__dirname, '/public/favicon.ico'))); +app.use(logger('dev')); +app.use(methodOverride()); +app.use( + session({ + resave: true, + saveUninitialized: true, + secret: 'uwotm8', + }) +); +app.use(bodyParser.json()); +app.use(bodyParser.urlencoded({ extended: true })); +app.use(multer()); +app.use(express.static(path.join(__dirname, 'public'))); + +app.get('/', routes.index); +app.get('/users', user.list); + +// error handling middleware should be loaded after the loading the routes +if (app.get('env') === 'development') { + app.use(errorHandler()); +} + +var server = http.createServer(app); +server.listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + + +Unless you need to work directly with the `http` module (socket.io/SPDY/HTTPS), loading it is not required, and the app can be simply started this way: + +```js +app.listen(app.get('port'), () => { + console.log('Express server listening on port ' + app.get('port')); +}); +``` + + + +### Run the app + +The migration process is complete, and the app is now an +Express 4 app. To confirm, start the app by using the following command: + +```bash +$ node . +``` + +Load [http://localhost:3000](http://localhost:3000) +and see the home page being rendered by Express 4. + +## Upgrading to the Express 4 app generator + +The command-line tool to generate an Express app is still +`express`, but to upgrade to the new version, you must uninstall +the Express 3 app generator and then install the new +`express-generator`. + +### Installing + +If you already have the Express 3 app generator installed on your system, +you must uninstall it: + +```bash +$ npm uninstall -g express +``` + +Depending on how your file and directory privileges are configured, +you might need to run this command with `sudo`. + +Now install the new generator: + +```bash +$ npm install -g express-generator +``` + +Depending on how your file and directory privileges are configured, +you might need to run this command with `sudo`. + +Now the `express` command on your system is updated to the +Express 4 generator. + +### Changes to the app generator + +Command options and use largely remain the same, with the following exceptions: + +* Removed the `--sessions` option. +* Removed the `--jshtml` option. +* Added the `--hogan` option to support [Hogan.js](http://twitter.github.io/hogan.js/). + +### Example + +Execute the following command to create an Express 4 app: + +```bash +$ express app4 +``` + +If you look at the contents of the `app4/app.js` file, you will notice +that all the middleware functions (except `express.static`) that are required for +the app are loaded as independent modules, and the `router` middleware +is no longer explicitly loaded in the app. + +You will also notice that the `app.js` file is now a Node.js module, in contrast to the standalone app that was generated by the old generator. + +After installing the dependencies, start the app by using the following command: + +```bash +$ npm start +``` + +If you look at the `npm start` script in the `package.json` file, +you will notice that the actual command that starts the app is +`node ./bin/www`, which used to be `node app.js` +in Express 3. + +Because the `app.js` file that was generated by the Express 4 generator +is now a Node.js module, it can no longer be started independently as an app +(unless you modify the code). The module must be loaded in a Node.js file +and started via the Node.js file. The Node.js file is `./bin/www` +in this case. + +Neither the `bin` directory nor the extensionless `www` +file is mandatory for creating an Express app or starting the app. They are +just suggestions made by the generator, so feel free to modify them to suit your +needs. + +To get rid of the `www` directory and keep things the "Express 3 way", +delete the line that says `module.exports = app;` at the end of the +`app.js` file, then paste the following code in its place: + +```js +app.set('port', process.env.PORT || 3000); + +var server = app.listen(app.get('port'), () => { + debug('Express server listening on port ' + server.address().port); +}); +``` + +Ensure that you load the `debug` module at the top of the `app.js` file by using the following code: + +```js +var debug = require('debug')('app4'); +``` + +Next, change `"start": "node ./bin/www"` in the `package.json` file to `"start": "node app.js"`. + +You have now moved the functionality of `./bin/www` back to +`app.js`. This change is not recommended, but the exercise helps you +to understand how the `./bin/www` file works, and why the `app.js` file +no longer starts on its own. diff --git a/src/content/pages/zh-tw/guide/migrating-5.mdx b/src/content/pages/zh-tw/guide/migrating-5.mdx new file mode 100644 index 0000000000..2a035c4e04 --- /dev/null +++ b/src/content/pages/zh-tw/guide/migrating-5.mdx @@ -0,0 +1,678 @@ +--- +title: Moving to Express 5 +description: A comprehensive guide to migrating your Express.js applications from version 4 to 5, detailing breaking changes, deprecated methods, and new improvements. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +Express 5 is not very different from Express 4; although it maintains the same basic API, there are still changes that break compatibility with the previous version. Therefore, an application built with Express 4 might not work if you update it to use Express 5. + +To install this version, you need to have a Node.js version 18 or higher. Then, execute the following command in your application directory: + +```sh +npm install "express@5" +``` + +You can then run your automated tests to see what fails, and fix problems according to the updates listed below. After addressing test failures, run your app to see what errors occur. You'll find out right away if the app uses any methods or properties that are not supported. + +## Express 5 Codemods + +To help you migrate your express server, we have created a set of codemods that will help you automatically update your code to the latest version of Express. + +Run the following command for run all the codemods available: + +```sh +npx codemod@latest @expressjs/v5-migration-recipe +``` + +If you want to run a specific codemod, you can run the following command: + +```sh +npx codemod@latest @expressjs/name-of-the-codemod +``` + +You can find the list of available codemods [here](https://codemod.link/express). + +## Changes in Express 5 + +**Removed methods and properties** + + + +**Changed** + + + +**Improvements** + + + +## Removed methods and properties + +If you use any of these methods or properties in your app, it will crash. So, you'll need to change your app after you update to version 5. + +### app.del() + +Express 5 no longer supports the `app.del()` function. If you use this function, an error is thrown. For registering HTTP DELETE routes, use the `app.delete()` function instead. + +Initially, `del` was used instead of `delete`, because `delete` is a reserved keyword in JavaScript. However, as of ECMAScript 6, `delete` and other reserved keywords can legally be used as property names. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/route-del-to-delete +``` + + + +```js +// v4 +app.del('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); + +// v5 +app.delete('/user/:id', (req, res) => { + res.send(`DELETE /user/${req.params.id}`); +}); +``` + +### app.param(fn) + +The `app.param(fn)` signature was used for modifying the behavior of the `app.param(name, fn)` function. It has been deprecated since v4.11.0, and Express 5 no longer supports it at all. + +### Pluralized method names + +The following method names have been pluralized. In Express 4, using the old methods resulted in a deprecation warning. Express 5 no longer supports them at all: + +`req.acceptsCharset()` is replaced by `req.acceptsCharsets()`. + +`req.acceptsEncoding()` is replaced by `req.acceptsEncodings()`. + +`req.acceptsLanguage()` is replaced by `req.acceptsLanguages()`. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/pluralize-method-names +``` + + + +```js +// v4 +app.all('/', (req, res) => { + req.acceptsCharset('utf-8'); + req.acceptsEncoding('br'); + req.acceptsLanguage('en'); + + // ... +}); + +// v5 +app.all('/', (req, res) => { + req.acceptsCharsets('utf-8'); + req.acceptsEncodings('br'); + req.acceptsLanguages('en'); + + // ... +}); +``` + +### Leading colon (:) in the name for app.param(name, fn) + +A leading colon character (:) in the name for the `app.param(name, fn)` function is a remnant of Express 3, and for the sake of backwards compatibility, Express 4 supported it with a deprecation notice. Express 5 will silently ignore it and use the name parameter without prefixing it with a colon. + +This should not affect your code if you follow the Express 4 documentation of [app.param](/en/4x/api#app.param), as it makes no mention of the leading colon. + +### req.param(name) + +This potentially confusing and dangerous method of retrieving form data has been removed. You will now need to specifically look for the submitted parameter name in the `req.params`, `req.body`, or `req.query` object. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/explicit-request-params +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + const id = req.param('id'); + const body = req.param('body'); + const query = req.param('query'); + + // ... +}); + +// v5 +app.post('/user', (req, res) => { + const id = req.params.id; + const body = req.body; + const query = req.query; + + // ... +}); +``` + +### res.json(obj, status) + +Express 5 no longer supports the signature `res.json(obj, status)`. Instead, set the status and then chain it to the `res.json()` method like this: `res.status(status).json(obj)`. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.json({ name: 'Ruben' }, 201); +}); + +// v5 +app.post('/user', (req, res) => { + res.status(201).json({ name: 'Ruben' }); +}); +``` + +### res.jsonp(obj, status) + +Express 5 no longer supports the signature `res.jsonp(obj, status)`. Instead, set the status and then chain it to the `res.jsonp()` method like this: `res.status(status).jsonp(obj)`. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.post('/user', (req, res) => { + res.jsonp({ name: 'Ruben' }, 201); +}); + +// v5 +app.post('/user', (req, res) => { + res.status(201).jsonp({ name: 'Ruben' }); +}); +``` + +### res.redirect(url, status) + +Express 5 no longer supports the signature `res.redirect(url, status)`. Instead, use the following signature: `res.redirect(status, url)`. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/redirect-arg-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('/users', 301); +}); + +// v5 +app.get('/user', (req, res) => { + res.redirect(301, '/users'); +}); +``` + +### res.redirect('back') and res.location('back') + +Express 5 no longer supports the magic string `back` in the `res.redirect()` and `res.location()` methods. Instead, use the `req.get('Referrer') || '/'` value to redirect back to the previous page. In Express 4, the `res.redirect('back')` and `res.location('back')` methods were deprecated. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/back-redirect-deprecated +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.redirect('back'); +}); + +// v5 +app.get('/user', (req, res) => { + res.redirect(req.get('Referrer') || '/'); +}); +``` + +### res.send(body, status) + +Express 5 no longer supports the signature `res.send(obj, status)`. Instead, set the status and then chain it to the `res.send()` method like this: `res.status(status).send(obj)`. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send({ name: 'Ruben' }, 200); +}); + +// v5 +app.get('/user', (req, res) => { + res.status(200).send({ name: 'Ruben' }); +}); +``` + +### res.send(status) + +Express 5 no longer supports the signature `res.send(status)`, where `status` is a number. Instead, use the `res.sendStatus(statusCode)` function, which sets the HTTP response header status code and sends the text version of the code: "Not Found", "Internal Server Error", and so on. +If you need to send a number by using the `res.send()` function, quote the number to convert it to a string, so that Express does not interpret it as an attempt to use the unsupported old signature. + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/status-send-order +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.send(200); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendStatus(200); +}); +``` + +### res.sendfile() + +The `res.sendfile()` function has been replaced by a camel-cased version `res.sendFile()` in Express 5. + +**Note:** In Express 5, `res.sendFile()` uses the `mime-types` package for MIME type detection, which returns different Content-Type values than Express 4 for several common file types: + +* JavaScript files (.js): now "text/javascript" instead of "application/javascript" +* JSON files (.json): now "application/json" instead of "text/json" +* CSS files (.css): now "text/css" instead of "text/plain" +* XML files (.xml): now "application/xml" instead of "text/xml" +* Font files (.woff): now "font/woff" instead of "application/font-woff" +* SVG files (.svg): now "image/svg+xml" instead of "application/svg+xml" + + +You can replace the deprecated signatures with the following command: + +```plaintext +npx codemod@latest @expressjs/camelcase-sendfile +``` + + + +```js +// v4 +app.get('/user', (req, res) => { + res.sendfile('/path/to/file'); +}); + +// v5 +app.get('/user', (req, res) => { + res.sendFile('/path/to/file'); +}); +``` + +### router.param(fn) + +The `router.param(fn)` signature was used for modifying the behavior of the `router.param(name, fn)` function. It has been deprecated since v4.11.0, and Express 5 no longer supports it at all. + +### express.static.mime + +In Express 5, `mime` is no longer an exported property of the `static` field. +Use the [`mime-types` package](https://github.com/jshttp/mime-types) to work with MIME type values. + +**Important:** This change affects not only direct usage of `express.static.mime` but also other Express methods that rely on MIME type detection, such as `res.sendFile()`. The following MIME types have changed from Express 4: + +* JavaScript files (.js): now served as "text/javascript" instead of "application/javascript" +* JSON files (.json): now served as "application/json" instead of "text/json" +* CSS files (.css): now served as "text/css" instead of "text/plain" +* HTML files (): now served as "text/html; charset=utf-8" instead of just "text/html" +* XML files (.xml): now served as "application/xml" instead of "text/xml" +* Font files (.woff): now served as "font/woff" instead of "application/font-woff" + +```js +// v4 +express.static.mime.lookup('json'); + +// v5 +const mime = require('mime-types'); +mime.lookup('json'); +``` + +### express:router debug logs + +In Express 5, router handling logic is performed by a dependency. Therefore, the +debug logs for the router are no longer available under the `express:` namespace. +In v4, the logs were available under the namespaces `express:router`, `express:router:layer`, +and `express:router:route`. All of these were included under the namespace `express:*`. +In v5.1+, the logs are available under the namespaces `router`, `router:layer`, and `router:route`. +The logs from `router:layer` and `router:route` are included in the namespace `router:*`. +To achieve the same detail of debug logging when using `express:*` in v4, use a conjunction of +`express:*`, `router`, and `router:*`. + +```sh + +DEBUG=express:* node index.js + + +DEBUG=express:*,router,router:* node index.js +``` + +## Changed + +### Path route matching syntax + +Path route matching syntax is when a string is supplied as the first parameter to the `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, and `router.use()` APIs. The following changes have been made to how the path string is matched to an incoming request: + +* The wildcard `*` must have a name, matching the behavior of parameters `:`, use `/*splat` instead of `/*` + +```js +// v4 +app.get('/*', async (req, res) => { + res.send('ok'); +}); + +// v5 +app.get('/*splat', async (req, res) => { + res.send('ok'); +}); +``` + + +`*splat` matches any path without the root path. If you need to match the root path as well `/`, you can use `/{*splat}`, wrapping the wildcard in braces. + +```js +// v5 +app.get('/{*splat}', async (req, res) => { + res.send('ok'); +}); +``` + + + +* The optional character `?` is no longer supported, use braces instead. + +```js +// v4 +app.get('/:file.:ext?', async (req, res) => { + res.send('ok'); +}); + +// v5 +app.get('/:file{.:ext}', async (req, res) => { + res.send('ok'); +}); +``` + +* Regexp characters are not supported. For example: + +```js +app.get('/[discussion|page]/:slug', async (req, res) => { + res.status(200).send('ok'); +}); +``` + +should be changed to: + +```js +app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { + res.status(200).send('ok'); +}); +``` + +* Some characters have been reserved to avoid confusion during upgrade (`()[]?+!`), use `\` to escape them. +* Parameter names now support valid JavaScript identifiers, or quoted like `:"this"`. + +### Rejected promises handled from middleware and handlers + +Request middleware and handlers that return rejected promises are now handled by forwarding the rejected value as an `Error` to the error handling middleware. This means that using `async` functions as middleware and handlers are easier than ever. When an error is thrown in an `async` function or a rejected promise is `await`ed inside an async function, those errors will be passed to the error handler as if calling `next(err)`. + +Details of how Express handles errors is covered in the [error handling documentation](/en/guide/error-handling). + +### express.urlencoded + +The `express.urlencoded` method makes the `extended` option `false` by default. + +### express.static dotfiles + +In Express 5, the `express.static` middleware's `dotfiles` option now defaults to `"ignore"`. This is a change from Express 4, where dotfiles were served by default. As a result, files inside a directory that starts with a dot (`.`), such as `.well-known`, will no longer be accessible and will return a **404 Not Found** error. This can break functionality that depends on serving dot-directories, such as Android App Links, and Apple Universal Links. + +Example of breaking code: + +```js +// v4 +app.use(express.static('public')); +``` + +After migrating to Express 5, a request to `/.well-known/assetlinks.json` will result in a **404 Not Found**. + +To fix this, serve specific dot-directories explicitly using the `dotfiles: "allow"` option: + +```js +// v5 +app.use('/.well-known', express.static('public/.well-known', { dotfiles: 'allow' })); +app.use(express.static('public')); +``` + +This approach allows you to safely serve only the intended dot-directories while keeping the default secure behavior for other dotfiles, which remain inaccessible. + +### app.listen + +In Express 5, the `app.listen` method will invoke the user-provided callback function (if provided) when the server receives an error event. In Express 4, such errors would be thrown. This change shifts error-handling responsibility to the callback function in Express 5. If there is an error, it will be passed to the callback as an argument. +For example: + +```js +const server = app.listen(8080, '0.0.0.0', (error) => { + if (error) { + throw error; // e.g. EADDRINUSE + } + console.log(`Listening on ${JSON.stringify(server.address())}`); +}); +``` + +### app.router + +The `app.router` object, which was removed in Express 4, has made a comeback in Express 5. In the new version, this object is a just a reference to the base Express router, unlike in Express 3, where an app had to explicitly load it. + +### req.body + +The `req.body` property returns `undefined` when the body has not been parsed. In Express 4, it returns `{}` by default. + +### req.host + +In Express 4, the `req.host` function incorrectly stripped off the port number if it was present. In Express 5, the port number is maintained. + +### req.params + +The `req.params` object now has a **null prototype** when using string paths. However, if the path is defined with a regular expression, `req.params` remains a standard object with a normal prototype. Additionally, there are two important behavioral changes: + +**Wildcard parameters are now arrays:** + +Wildcards (e.g., `/*splat`) capture path segments as an array instead of a single string. + +```js +app.get('/*splat', (req, res) => { + // GET /foo/bar + console.dir(req.params); + // => [Object: null prototype] { splat: [ 'foo', 'bar' ] } +}); +``` + +**Unmatched parameters are omitted:** + +In Express 4, unmatched wildcards were empty strings (`''`) and optional `:` parameters (using `?`) had a key with value `undefined`. In Express 5, unmatched parameters are completely omitted from `req.params`. + +```js +// v4: unmatched wildcard is empty string +app.get('/*', (req, res) => { + // GET / + console.dir(req.params); + // => { '0': '' } +}); + +// v4: unmatched optional param is undefined +app.get('/:file.:ext?', (req, res) => { + // GET /image + console.dir(req.params); + // => { file: 'image', ext: undefined } +}); + +// v5: unmatched optional param is omitted +app.get('/:file{.:ext}', (req, res) => { + // GET /image + console.dir(req.params); + // => [Object: null prototype] { file: 'image' } +}); +``` + +### req.query + +The `req.query` property is no longer a writable property and is instead a getter. The default query parser has been changed from "extended" to "simple". + +### res.clearCookie + +The `res.clearCookie` method ignores the `maxAge` and `expires` options provided by the user. + +### res.status + +The `res.status` method only accepts integers in the range of `100` to `999`, following the behavior defined by Node.js, and it returns an error when the status code is not an integer. + +### res.vary + +The `res.vary` throws an error when the `field` argument is missing. In Express 4, if the argument was omitted, it gave a warning in the console + +## Improvements + +### res.render() + +This method now enforces asynchronous behavior for all view engines, avoiding bugs caused by view engines that had a synchronous implementation and that violated the recommended interface. + +### Brotli encoding support + +Express 5 supports Brotli encoding for requests received from clients that support it. diff --git a/src/content/pages/zh-tw/resources/glossary.mdx b/src/content/pages/zh-tw/resources/glossary.mdx new file mode 100644 index 0000000000..e94e59ab60 --- /dev/null +++ b/src/content/pages/zh-tw/resources/glossary.mdx @@ -0,0 +1,61 @@ +--- +title: Glossary +description: A comprehensive glossary of terms related to Express.js, Node.js, middleware, routing, and other key concepts to help you understand and use Express effectively. +--- + +import Alert from '@components/primitives/Alert/Alert.astro'; + +### application + +In general, one or more programs that are designed to carry out operations for a specific purpose. In the context of Express, a program that uses the Express API running on the Node.js platform. Might also refer to an [app object](/en/api#express). + +### API + +Application programming interface. Spell out the abbreviation when it is first used. + +### Express + +A fast, un-opinionated, minimalist web framework for Node.js applications. In general, "Express" is preferred to "Express.js," though the latter is acceptable. + +### libuv + +A multi-platform support library which focuses on asynchronous I/O, primarily developed for use by Node.js. + +### middleware + +A function that is invoked by the Express routing layer before the final request handler, and thus sits in the middle between a raw request and the final intended route. A few fine points of terminology around middleware: + +* `var foo = require('middleware')` is called *requiring* or *using* a Node.js module. Then the statement `var mw = foo()` typically returns the middleware. +* `app.use(mw)` is called *adding the middleware to the global processing stack*. +* `app.get('/foo', mw, function (req, res) { ... })` is called *adding the middleware to the "GET /foo" processing stack*. + +### Node.js + +A software platform that is used to build scalable network applications. Node.js uses JavaScript as its scripting language, and achieves high throughput via non-blocking I/O and a single-threaded event loop. See [nodejs.org](https://nodejs.org/en/). **Usage note**: Initially, "Node.js," thereafter "Node". + +### open-source, open source + +When used as an adjective, hyphenate; for example: "This is open-source software." See [Open-source software on Wikipedia](http://en.wikipedia.org/wiki/Open-source_software). + + + +Although it is common not to hyphenate this term, we are using the standard English rules for +hyphenating a compound adjective. + + + +### request + +An HTTP request. A client submits an HTTP request message to a server, which returns a response. The request must use one of several [request methods](https://en.wikipedia.org/wiki/Hypertext_Transfer_Protocol#Request_methods) such as GET, POST, and so on. + +### response + +An HTTP response. A server returns an HTTP response message to the client. The response contains completion status information about the request and might also contain requested content in its message body. + +### route + +Part of a URL that identifies a resource. For example, in `http://foo.com/products/id`, "/products/id" is the route. + +### router + +See [router](/en/api#router) in the API reference. diff --git a/src/content/pages/zh-tw/resources/utils.md b/src/content/pages/zh-tw/resources/utils.md new file mode 100644 index 0000000000..3a8b0a5be1 --- /dev/null +++ b/src/content/pages/zh-tw/resources/utils.md @@ -0,0 +1,22 @@ +--- +title: Express utilities +description: Discover utility modules related to Express.js and Node.js, including tools for cookies, CSRF protection, URL parsing, routing, and more to enhance your applications. +--- + +## Express utility functions + +The [pillarjs](https://github.com/pillarjs) GitHub organization contains a number of modules +for utility functions that may be generally useful. + +| Utility modules | Description | +| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [cookies](https://www.npmjs.com/package/cookies) | Get and set HTTP(S) cookies that can be signed to prevent tampering, using Keygrip. Can be used with the Node.js HTTP library or as Express middleware. | +| [csrf](https://www.npmjs.com/package/csrf) | Contains the logic behind CSRF token creation and verification. Use this module to create custom CSRF middleware. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Function to invoke as the final step to respond to HTTP request. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Parse a URL with caching. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Turn an Express-style path string such as \`\`/user/:name\` into a regular expression. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Resolves a relative path against a root path with validation. | +| [router](https://www.npmjs.com/package/router) | Simple middleware-style router. | +| [send](https://www.npmjs.com/package/send) | Library for streaming files as a HTTP response, with support for partial responses (ranges), conditional-GET negotiation, and granular events. | + +For additional low-level HTTP-related modules, see [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/zh-tw/support.md b/src/content/pages/zh-tw/support.md new file mode 100644 index 0000000000..68763b76f0 --- /dev/null +++ b/src/content/pages/zh-tw/support.md @@ -0,0 +1,23 @@ +--- +title: Version Support +description: Find information about the support schedule for different Express.js versions, including which versions are currently maintained and end-of-life policies. +--- + +Only the latest version of any given major release line is supported. + +Versions that are EOL (end-of-life) _may_ receive updates for critical security vulnerabilities, but the Express team offers no guarantee and does not plan to address or release fixes for any issues found. + +| Major Version | Minimum Node.js Version | Support Start Date | Support End Date | +| ------------------------------------------- | --------------------------------------- | ------------------ | ---------------- | +| [**v5.x**](/en/5x/api) | 18 | September 2024 | **ongoing** | +| [**v4.x**](/en/4x/api) | 0.10.0 | April 2014 | **ongoing** | +| [**v3.x**](/en/3x/api) | 0.8.0 | October 2012 | July 2015 | +| [**v2.x**](/2x/) | 0.4.1 | March 2011 | July 2012 | +| **v1.x** | 0.2.0 | December 2010 | March 2011 | +| **v0.14.x** | 0.1.98 | December 2010 | December 2010 | + +## Commercial Support Options + +If you are unable to update to a supported version of Express, please contact one of our partners to receive security updates: + +- [HeroDevs Never-Ending Support](http://www.herodevs.com/support/express-nes?utm_source=expressjs&utm_medium=link&utm_campaign=express_eol_page) diff --git a/src/i18n/ui/de.json b/src/i18n/ui/de.json index 287ad4fce2..763fa10a6d 100644 --- a/src/i18n/ui/de.json +++ b/src/i18n/ui/de.json @@ -1,49 +1,46 @@ { "home": { - "welcome": "Willkommen", - "workInProgress": "Diese Startseite befindet sich noch in Arbeit.", + "welcome": "Begrüßung", + "workInProgress": "Dies ist eine Work-in-progress Homepage.", "reviewDesignSystem": { - "prefix": "Sehen Sie sich die", + "prefix": "Überprüfen Sie die", "link": "Design System Foundations", - "suffix": "Demo-Seite an, um alle Tokens, Primitive und Muster zu erkunden." + "suffix": "Demo-Seite, um alle Token, Primitive und Muster zu erkunden." } }, "search": { - "placeholder": "Tippen Sie, um zu beginnen...", - "ariaLabel": "Tippen Sie, um zu suchen" + "placeholder": "Tippe ein...", + "ariaLabel": "Tippen zum Suchen starten" }, "theme": { - "toggle": "Design umschalten", - "switchToLight": "Zum hellen Modus wechseln", + "toggle": "Theme umschalten", + "switchToLight": "Zum Lichtmodus wechseln", "switchToDark": "Zum dunklen Modus wechseln" }, "version": { "selectLabel": "API-Version auswählen" }, - "language": { - "selectLabel": "Sprache auswählen" - }, "nav": { "mainMenu": "Hauptmenü", "toggleMenu": "Menü umschalten", - "home": "Startseite", - "breadcrumb": "Brotkrumen", + "home": "home", + "breadcrumb": "Breadcrumb", "mainNavigation": "Hauptnavigation", "selectVersion": "Dokumentationsversion auswählen" }, "menu": { "main": { - "docs": "Dokumentation", + "docs": "Texte", "api": "API", "resources": "Ressourcen", "blog": "Blog", - "support": "Support" + "support": "Unterstützung" }, "sections": { "gettingStarted": "Erste Schritte", - "guide": "Leitfaden", - "migration": "Migrationsleitfäden", - "advanced": "Fortgeschrittene Themen", + "guide": "Anleitung", + "migration": "Migrationsanleitungen", + "advanced": "Erweiterte Themen", "express": "express()", "application": "Anwendung", "request": "Anfrage", @@ -52,11 +49,11 @@ "middleware": "Middleware" }, "items": { - "installing": "Installation", + "installing": "Installiere", "helloWorld": "Hallo Welt", "expressGenerator": "Express-Generator", - "basicRouting": "Grundlegendes Routing", - "staticFiles": "Statische Dateien bereitstellen", + "basicRouting": "Basisrouting", + "staticFiles": "Serviere statische Dateien", "examples": "Beispiele", "faq": "FAQ", "routing": "Routing", @@ -64,16 +61,16 @@ "usingMiddleware": "Middleware verwenden", "usingTemplateEngines": "Template-Engines verwenden", "errorHandling": "Fehlerbehandlung", - "debugging": "Debugging", + "debugging": "Debuggen", "behindProxies": "Hinter Proxys", "databaseIntegration": "Datenbankintegration", - "overridingExpressApi": "Express-API überschreiben", - "migratingTo4": "Migration zu Express 4", - "migratingTo5": "Migration zu Express 5", - "buildingTemplateEngines": "Template-Engines erstellen", - "bestPracticePerformance": "Best Practices für Performance", - "bestPracticeSecurity": "Best Practices für Sicherheit", - "healthcheckGracefulShutdown": "Health Checks & Graceful Shutdown", + "overridingExpressApi": "Überschreiben der Express-API", + "migratingTo4": "Umzug nach Express 4", + "migratingTo5": "Umzug nach Express 5", + "buildingTemplateEngines": "Bauvorlagen-Engines", + "bestPracticePerformance": "Best Practices", + "bestPracticeSecurity": "Sicherheits-Best Practices", + "healthcheckGracefulShutdown": "Gesundheitschecks & anmutiges Herunterfahren", "securityUpdates": "Sicherheitsupdates", "overview": "Übersicht", "properties": "Eigenschaften", @@ -81,9 +78,9 @@ "events": "Ereignisse", "types": "Integriert", "community": "Community", - "glossary": "Glossar", + "glossary": "Glossary", "contributing": "Mitwirken", - "utils": "Hilfsprogramme", + "utils": "Hilfsmittel", "middleware": "Middleware" }, "aria": { @@ -91,37 +88,37 @@ "api": "API-Referenz", "resources": "Ressourcen", "blog": "Blog", - "support": "Support", + "support": "Unterstützung", "installing": "Express installieren", - "helloWorld": "Hallo-Welt-Beispiel", + "helloWorld": "Hallo Weltbeispiel", "expressGenerator": "Express-Generator", - "routing": "Routing-Leitfaden", - "writingMiddleware": "Middleware schreiben Leitfaden", - "usingMiddleware": "Middleware verwenden Leitfaden", - "usingTemplateEngines": "Template-Engines Leitfaden", - "errorHandling": "Fehlerbehandlung Leitfaden", - "debugging": "Express debuggen", - "behindProxies": "Express hinter Proxys", - "databaseIntegration": "Datenbankintegration Leitfaden", - "overridingExpressApi": "Express-API überschreiben Leitfaden", + "routing": "Routenanleitung", + "writingMiddleware": "Middleware-Anleitung schreiben", + "usingMiddleware": "Middleware-Anleitung verwenden", + "usingTemplateEngines": "Hilfe für Template-Engines", + "errorHandling": "Fehler beim Handling", + "debugging": "Debuggen Express", + "behindProxies": "Express hinter Proxies", + "databaseIntegration": "Datenbank-Integrationshandbuch", + "overridingExpressApi": "Überschreiben der Express-API-Anleitung", "application": "Anwendungsübersicht", - "request": "Anfrageübersicht", + "request": "Übersicht anfordern", "response": "Antwortübersicht", "router": "Routerübersicht", "middleware": "Middleware-Ressourcen", "community": "Community-Ressourcen", - "glossary": "Begriffsglossar", - "contributing": "Mitwirkungsleitfaden", - "utils": "Hilfsprogramme" + "glossary": "Glossar der Begriffe", + "contributing": "Beitragende Anleitung", + "utils": "Hilfsmittel" } }, "doc": { - "previousPage": "Zurück", - "nextPage": "Weiter", - "pageNavigation": "Seitennavigation" + "previousPage": "Vorherige", + "nextPage": "Nächste", + "pageNavigation": "Page navigation" }, "page": { - "editOnGitHub": "Auf GitHub bearbeiten", + "editOnGitHub": "Edit on GitHub", "translateThis": "Diese Seite übersetzen" }, "post": { @@ -137,41 +134,41 @@ "linkCopied": "Link kopiert!", "toc": "Auf dieser Seite", "more": "Mehr von Express", - "writeBanner": "Interessiert, einen Beitrag zu schreiben?\nSehen Sie sich unsere Richtlinien an, um zu beginnen.", - "writeGuidelines": "Richtlinien lesen" + "writeBanner": "Möchten Sie einen Beitrag schreiben? \n Schauen Sie sich unsere Richtlinien an, um loszulegen.", + "writeGuidelines": "Lies die Richtlinien" }, "toc": { "overview": "Übersicht" }, "features": { - "title": "Klarheit statt Komplexität. Für jeden Entwickler.", + "title": "Klarheit über die Komplexität. Für jeden Entwickler.", "performance": { - "title": "Performance", - "body": "Express bietet eine schlanke Schicht grundlegender Webfunktionen, ohne Node.js-Funktionen zu verbergen." + "title": "Leistung", + "body": "Express bietet eine dünne Schicht von grundlegenden Web-Applikations-Funktionen, ohne verschleiernde Node.js Funktionen, die Sie kennen und lieben." }, "api": { "title": "APIs", - "body": "Mit zahlreichen HTTP-Utilities und Middleware lassen sich robuste APIs schnell erstellen." + "body": "Mit einer Vielzahl von HTTP-Utility-Methoden und Middleware steht Ihnen eine robuste API zu erstellen ist schnell und einfach." }, "middleware": { "title": "Middleware", - "body": "Express ist ein leichtgewichtiges und flexibles Routing-Framework, das durch Middleware erweitert wird." + "body": "Express ist ein leichtes, flexibles Routing-Framework mit minimalen Kernfunktionen, die durch den Einsatz von Express-Middleware-Modulen ergänzt werden sollen." }, "webapplication": { - "title": "Webanwendungen", - "body": "Express ist ein minimalistisches und flexibles Framework für Web- und Mobile-Anwendungen." + "title": "Web-Anwendungen", + "body": "Express ist ein minimales und flexibles Node.js Web Application Framework, das eine robuste Reihe von Funktionen für Web- und mobile Anwendungen bietet." } }, "error404": { "title": "404 - Seite nicht gefunden", - "description": "Die gesuchte Seite wurde nicht gefunden.", + "description": "Die gesuchte Seite konnte nicht gefunden werden.", "heading": "Seite nicht gefunden", - "message": "Die Seite existiert nicht oder wurde verschoben.", - "goHome": "Zur Startseite" + "message": "Die gesuchte Seite existiert nicht oder wurde verschoben.", + "goHome": "Gehe zu Zuhause" }, "hero": { - "tagline": "Schnelles, minimalistisches Web-Framework für Node.js", - "getStarted": "Loslegen", + "tagline": "Schnell, unüberlegtes, minimalistisches Web-Framework für Node.js", + "getStarted": "Los geht's", "videoPause": "Hintergrundvideo pausieren", "videoPlay": "Hintergrundvideo abspielen" } diff --git a/src/i18n/ui/es.json b/src/i18n/ui/es.json index ace5893d13..7954faf7c4 100644 --- a/src/i18n/ui/es.json +++ b/src/i18n/ui/es.json @@ -1,114 +1,111 @@ { "home": { - "welcome": "Bienvenido", - "workInProgress": "Esta es una página de inicio en desarrollo.", + "welcome": "Bienvenida", + "workInProgress": "Esta es una página de trabajo en progreso.", "reviewDesignSystem": { - "prefix": "Revisa la", - "link": "Base del Sistema de Diseño", - "suffix": "página de demostración para explorar todos los tokens, primitivas y patrones." + "prefix": "Revisar el", + "link": "Fundaciones del sistema de diseño", + "suffix": "página de demostración para explorar todos los tokens, primitivos y patrones." } }, "search": { - "placeholder": "Empieza a escribir...", - "ariaLabel": "Empieza a escribir para buscar" + "placeholder": "Comience a escribir...", + "ariaLabel": "Empezar a escribir para buscar" }, "theme": { "toggle": "Cambiar tema", - "switchToLight": "Cambiar a modo claro", + "switchToLight": "Cambiar al modo de luz", "switchToDark": "Cambiar a modo oscuro" }, "version": { - "selectLabel": "Seleccionar versión de API" - }, - "language": { - "selectLabel": "Seleccionar idioma" + "selectLabel": "Seleccionar versión API" }, "nav": { "mainMenu": "Menú principal", - "toggleMenu": "Alternar menú", - "home": "inicio", - "breadcrumb": "Ruta de navegación", + "toggleMenu": "Cambiar menú", + "home": "casa", + "breadcrumb": "migas de pan", "mainNavigation": "Navegación principal", - "selectVersion": "Seleccionar versión de la documentación" + "selectVersion": "Seleccione la versión de documentación" }, "menu": { "main": { - "docs": "Documentación", + "docs": "Documentos", "api": "API", "resources": "Recursos", "blog": "Blog", "support": "Soporte" }, "sections": { - "gettingStarted": "Primeros pasos", + "gettingStarted": "Comenzando", "guide": "Guía", - "migration": "Guías de migración", + "migration": "Guías de Migración", "advanced": "Temas avanzados", "express": "express()", "application": "Aplicación", "request": "Solicitud", "response": "Respuesta", - "router": "Router", - "middleware": "Middleware" + "router": "Enrutador", + "middleware": "Medios" }, "items": { - "installing": "Instalación", + "installing": "Instalando", "helloWorld": "Hola mundo", - "expressGenerator": "Generador de Express", - "basicRouting": "Enrutamiento básico", - "staticFiles": "Archivos estáticos", + "expressGenerator": "Generador exprés", + "basicRouting": "Ruta básica", + "staticFiles": "Subrayando archivos estáticos", "examples": "Ejemplos", - "faq": "Preguntas frecuentes", - "routing": "Enrutamiento", - "writingMiddleware": "Escribir middleware", - "usingMiddleware": "Usar middleware", - "usingTemplateEngines": "Usar motores de plantillas", + "faq": "FAQ", + "routing": "Ruta", + "writingMiddleware": "Escribiendo middleware", + "usingMiddleware": "Usando middleware", + "usingTemplateEngines": "Utilizando motores de plantillas", "errorHandling": "Manejo de errores", "debugging": "Depuración", - "behindProxies": "Detrás de proxies", - "databaseIntegration": "Integración con bases de datos", - "overridingExpressApi": "Sobrescribir la API de Express", - "migratingTo4": "Migrar a Express 4", - "migratingTo5": "Migrar a Express 5", - "buildingTemplateEngines": "Crear motores de plantillas", - "bestPracticePerformance": "Buenas prácticas de rendimiento", + "behindProxies": "Behind proxies", + "databaseIntegration": "Integración de la base de datos", + "overridingExpressApi": "Reemplazar la API Express", + "migratingTo4": "Moviendo a Express 4", + "migratingTo5": "Moviendo a Express 5", + "buildingTemplateEngines": "Construcción de motores de plantillas", + "bestPracticePerformance": "Mejores prácticas de rendimiento", "bestPracticeSecurity": "Buenas prácticas de seguridad", - "healthcheckGracefulShutdown": "Health checks y apagado elegante", - "securityUpdates": "Actualizaciones de seguridad", + "healthcheckGracefulShutdown": "Revisiones de salud y apagado con gracia", + "securityUpdates": "Actualización de seguridad", "overview": "Resumen", "properties": "Propiedades", "methods": "Métodos", "events": "Eventos", "types": "Integrado", "community": "Comunidad", - "glossary": "Glosario", - "contributing": "Contribuir", + "glossary": "Glossary", + "contributing": "Contribuyendo", "utils": "Utilidades", - "middleware": "Middleware" + "middleware": "Medios" }, "aria": { "docs": "Documentación", - "api": "Referencia de API", + "api": "Referencia API", "resources": "Recursos", "blog": "Blog", "support": "Soporte", - "installing": "Instalar Express", - "helloWorld": "Ejemplo Hola mundo", - "expressGenerator": "Generador de Express", - "routing": "Guía de enrutamiento", - "writingMiddleware": "Guía para escribir middleware", - "usingMiddleware": "Guía para usar middleware", - "usingTemplateEngines": "Guía de motores de plantillas", + "installing": "Instalando Express", + "helloWorld": "Hola ejemplo de mundo", + "expressGenerator": "Generador exprés", + "routing": "Guía de ruta", + "writingMiddleware": "Guía de middleware de escritura", + "usingMiddleware": "Usando la guía de middleware", + "usingTemplateEngines": "Usando la guía de motores de plantillas", "errorHandling": "Guía de manejo de errores", - "debugging": "Depuración de Express", - "behindProxies": "Express detrás de proxies", - "databaseIntegration": "Guía de integración de bases de datos", - "overridingExpressApi": "Guía para sobrescribir la API de Express", + "debugging": "Depuración Express", + "behindProxies": "Expresar detrás de proxies", + "databaseIntegration": "Guía de integración de base de datos", + "overridingExpressApi": "Reemplazar la guía Express API", "application": "Resumen de la aplicación", - "request": "Resumen de la solicitud", - "response": "Resumen de la respuesta", - "router": "Resumen del router", - "middleware": "Recursos de middleware", + "request": "Resumen de solicitudes", + "response": "Respuesta general", + "router": "Resumen de ruta", + "middleware": "Recursos de Middleware", "community": "Recursos de la comunidad", "glossary": "Glosario de términos", "contributing": "Guía de contribución", @@ -118,10 +115,10 @@ "doc": { "previousPage": "Anterior", "nextPage": "Siguiente", - "pageNavigation": "Navegación de la página" + "pageNavigation": "Page navigation" }, "page": { - "editOnGitHub": "Editar en GitHub", + "editOnGitHub": "Edit on GitHub", "translateThis": "Traducir esta página" }, "post": { @@ -137,8 +134,8 @@ "linkCopied": "¡Enlace copiado!", "toc": "En esta página", "more": "Más de Express", - "writeBanner": "¿Te interesa escribir una publicación?\nConsulta nuestras guías para comenzar.", - "writeGuidelines": "Leer las guías" + "writeBanner": "¿Interesado en escribir una publicación? \n Revisa nuestras directrices para empezar.", + "writeGuidelines": "Leer las directrices" }, "toc": { "overview": "Resumen" @@ -147,32 +144,32 @@ "title": "Claridad sobre complejidad. Para cada desarrollador.", "performance": { "title": "Rendimiento", - "body": "Express proporciona una capa ligera de funcionalidades web sin ocultar las características de Node.js." + "body": "Express proporciona una capa delgada de características fundamentales de la aplicación web, sin ocultar las características de Node.js que usted conoce y ama." }, "api": { "title": "APIs", - "body": "Con múltiples utilidades HTTP y middleware, crear una API robusta es rápido y sencillo." + "body": "Con una infinidad de métodos de utilidad HTTP y middleware a tu disposición, crear una API robusta es rápido y fácil." }, "middleware": { - "title": "Middleware", - "body": "Express es un framework ligero y flexible que se puede ampliar mediante middleware." + "title": "Medios", + "body": "Express es un marco de enrutamiento ligero y flexible, con características básicas mínimas destinadas a ser incrementado mediante el uso de módulos Express middleware." }, "webapplication": { - "title": "Aplicaciones web", - "body": "Express es un framework minimalista y flexible para aplicaciones web y móviles." + "title": "Aplicaciones Web", + "body": "Express es un marco de aplicación web de Node.js mínimo y flexible que proporciona un robusto conjunto de características para aplicaciones web y móviles." } }, "error404": { "title": "404 - Página no encontrada", - "description": "No se pudo encontrar la página que buscas.", + "description": "La página que estás buscando no se pudo encontrar.", "heading": "Página no encontrada", - "message": "La página no existe o ha sido movida.", - "goHome": "Ir al inicio" + "message": "La página que buscas no existe o ha sido movida.", + "goHome": "Ir a Inicio" }, "hero": { - "tagline": "Framework web rápido y minimalista para Node.js", - "getStarted": "Comenzar", - "videoPause": "Pausar video de fondo", - "videoPlay": "Reproducir video de fondo" + "tagline": "Marco web para Node.js rápido, sin opinión y minimalista", + "getStarted": "Empezar", + "videoPause": "Pausar vídeo de fondo", + "videoPlay": "Reproducir vídeo de fondo" } } diff --git a/src/i18n/ui/fr.json b/src/i18n/ui/fr.json index 280ab48600..6864fac1f6 100644 --- a/src/i18n/ui/fr.json +++ b/src/i18n/ui/fr.json @@ -1,11 +1,11 @@ { "home": { "welcome": "Bienvenue", - "workInProgress": "Ceci est une page d’accueil en cours de développement.", + "workInProgress": "Ceci est une page d'accueil en cours de travail.", "reviewDesignSystem": { - "prefix": "Consultez la", - "link": "Base du système de design", - "suffix": "page de démonstration pour explorer tous les tokens, primitives et modèles." + "prefix": "Examiner le", + "link": "Conception des fondations du système", + "suffix": "page de démonstration pour explorer tous les jetons, primitives et motifs." } }, "search": { @@ -13,75 +13,72 @@ "ariaLabel": "Commencez à taper pour rechercher" }, "theme": { - "toggle": "Changer le thème", - "switchToLight": "Passer en mode clair", - "switchToDark": "Passer en mode sombre" + "toggle": "Basculer le thème", + "switchToLight": "Basculer en mode lumière", + "switchToDark": "Basculer en mode sombre" }, "version": { - "selectLabel": "Sélectionner la version de l’API" - }, - "language": { - "selectLabel": "Sélectionner la langue" + "selectLabel": "Sélectionnez la version de l'API" }, "nav": { "mainMenu": "Menu principal", - "toggleMenu": "Afficher/masquer le menu", - "home": "accueil", - "breadcrumb": "Fil d’Ariane", + "toggleMenu": "Afficher/Masquer le menu", + "home": "maison", + "breadcrumb": "Fil d'Ariane", "mainNavigation": "Navigation principale", - "selectVersion": "Sélectionner la version de la documentation" + "selectVersion": "Sélectionnez la version de la documentation" }, "menu": { "main": { - "docs": "Documentation", + "docs": "Documents", "api": "API", - "resources": "Ressources", - "blog": "Blog", - "support": "Support" + "resources": "Ressource", + "blog": "Blogue", + "support": "Soutien" }, "sections": { - "gettingStarted": "Premiers pas", - "guide": "Guide", + "gettingStarted": "Commencer", + "guide": "Tutoriel", "migration": "Guides de migration", "advanced": "Sujets avancés", "express": "express()", "application": "Application", - "request": "Requête", + "request": "Demander", "response": "Réponse", "router": "Routeur", "middleware": "Middleware" }, "items": { - "installing": "Installation", + "installing": "Installation en cours", "helloWorld": "Bonjour le monde", "expressGenerator": "Générateur Express", "basicRouting": "Routage de base", - "staticFiles": "Fichiers statiques", + "staticFiles": "Servir les fichiers statiques", "examples": "Exemples", - "faq": "FAQ", + "faq": "Foire Aux Questions", "routing": "Routage", - "writingMiddleware": "Écrire un middleware", - "usingMiddleware": "Utiliser un middleware", - "usingTemplateEngines": "Utiliser des moteurs de templates", + "writingMiddleware": "Écriture du middleware", + "usingMiddleware": "Utilisation du middleware", + "usingTemplateEngines": "Utiliser les moteurs de gabarits", "errorHandling": "Gestion des erreurs", "debugging": "Débogage", - "behindProxies": "Derrière des proxys", - "databaseIntegration": "Intégration de base de données", - "overridingExpressApi": "Remplacer l’API Express", - "migratingTo4": "Migrer vers Express 4", - "migratingTo5": "Migrer vers Express 5", - "buildingTemplateEngines": "Créer des moteurs de templates", - "bestPracticePerformance": "Bonnes pratiques de performance", - "bestPracticeSecurity": "Bonnes pratiques de sécurité", - "healthcheckGracefulShutdown": "Vérifications de santé et arrêt gracieux", + "behindProxies": "Derrière les proxies", + "databaseIntegration": "Intégration de la base de données", + "overridingExpressApi": "Outrepasser l'API Express", + "migratingTo4": "Déplacement vers Express 4", + "migratingTo5": "Déplacement vers Express 5", + "buildingTemplateEngines": "Construire des moteurs de gabarits", + "bestPracticePerformance": "Meilleures pratiques de performance", + "bestPracticeSecurity": "Meilleures pratiques de sécurité", + "healthcheckGracefulShutdown": "Extinction gracieuse des contrôles de santé", "securityUpdates": "Mises à jour de sécurité", "overview": "Aperçu", "properties": "Propriétés", "methods": "Méthodes", - "events": "Événements", - "types": "Intégré", + "events": "Évènements", + "types": "Intégrée", "community": "Communauté", - "glossary": "Glossaire", + "glossary": "Glossary", "contributing": "Contribuer", "utils": "Utilitaires", "middleware": "Middleware" @@ -89,27 +86,27 @@ "aria": { "docs": "Documentation", "api": "Référence API", - "resources": "Ressources", - "blog": "Blog", - "support": "Support", - "installing": "Installer Express", - "helloWorld": "Exemple Bonjour le monde", + "resources": "Ressource", + "blog": "Blogue", + "support": "Soutien", + "installing": "Installation Express", + "helloWorld": "Bonjour l'exemple du monde", "expressGenerator": "Générateur Express", "routing": "Guide de routage", - "writingMiddleware": "Guide pour écrire un middleware", - "usingMiddleware": "Guide pour utiliser un middleware", - "usingTemplateEngines": "Guide des moteurs de templates", + "writingMiddleware": "Écriture du tutoriel middleware", + "usingMiddleware": "Utilisation du tutoriel du middleware", + "usingTemplateEngines": "Utilisation du guide des moteurs de gabarits", "errorHandling": "Guide de gestion des erreurs", "debugging": "Débogage Express", - "behindProxies": "Express derrière des proxys", - "databaseIntegration": "Guide d’intégration de base de données", - "overridingExpressApi": "Guide pour remplacer l’API Express", - "application": "Aperçu de l’application", + "behindProxies": "Exprimez derrière les mandataires", + "databaseIntegration": "Guide d'intégration de la base de données", + "overridingExpressApi": "Outrepasser le guide de l'API Express", + "application": "Aperçu de l'application", "request": "Aperçu de la requête", "response": "Aperçu de la réponse", "router": "Aperçu du routeur", - "middleware": "Ressources middleware", - "community": "Ressources communautaires", + "middleware": "Ressources Middleware", + "community": "Ressources de la communauté", "glossary": "Glossaire des termes", "contributing": "Guide de contribution", "utils": "Utilitaires" @@ -118,10 +115,10 @@ "doc": { "previousPage": "Précédent", "nextPage": "Suivant", - "pageNavigation": "Navigation de page" + "pageNavigation": "Page navigation" }, "page": { - "editOnGitHub": "Modifier sur GitHub", + "editOnGitHub": "Edit on GitHub", "translateThis": "Traduire cette page" }, "post": { @@ -136,41 +133,41 @@ "copyLink": "Copier le lien", "linkCopied": "Lien copié !", "toc": "Sur cette page", - "more": "Plus d’Express", - "writeBanner": "Envie d’écrire un article ?\nConsultez nos directives pour commencer.", - "writeGuidelines": "Lire les directives" + "more": "En savoir plus sur Express", + "writeBanner": "Vous souhaitez écrire un message ? \n Consultez nos consignes pour commencer.", + "writeGuidelines": "Lisez les directives" }, "toc": { "overview": "Aperçu" }, "features": { - "title": "La clarté plutôt que la complexité. Pour chaque développeur.", + "title": "La clarté sur la complexité. Pour chaque développeur.", "performance": { - "title": "Performance", - "body": "Express fournit une couche légère de fonctionnalités web sans masquer celles de Node.js." + "title": "Performances", + "body": "Express fournit une couche mince de fonctionnalités Web fondamentales, sans obscurcir les fonctionnalités de Node.js que vous connaissez et aimez." }, "api": { "title": "APIs", - "body": "Avec de nombreuses utilités HTTP et middleware, créer une API robuste est simple et rapide." + "body": "Avec une myriade de méthodes HTTP utilitaires et de middleware à votre disposition, créer une API robuste est rapide et facile." }, "middleware": { "title": "Middleware", - "body": "Express est un framework léger et flexible extensible via des middleware." + "body": "Express est un framework de routage léger et souple avec des fonctionnalités de base minimales destinées à être augmentées grâce à l'utilisation de modules middleware Express." }, "webapplication": { - "title": "Applications web", - "body": "Express est un framework minimaliste et flexible pour les applications web et mobiles." + "title": "Applications Web", + "body": "Express est un framework d'application web Node.js minimal et flexible qui fournit un ensemble robuste de fonctionnalités pour les applications web et mobile." } }, "error404": { - "title": "404 - Page non trouvée", - "description": "La page que vous recherchez est introuvable.", - "heading": "Page non trouvée", - "message": "La page n’existe pas ou a été déplacée.", - "goHome": "Aller à l’accueil" + "title": "404 - Page introuvable", + "description": "La page que vous cherchez est introuvable.", + "heading": "Page introuvable", + "message": "La page que vous cherchez n'existe pas ou a été déplacée.", + "goHome": "Aller à la page d'accueil" }, "hero": { - "tagline": "Framework web rapide et minimaliste pour Node.js", + "tagline": "Cadre web rapide, sans opinion et minimaliste pour Node.js", "getStarted": "Commencer", "videoPause": "Mettre en pause la vidéo de fond", "videoPlay": "Lire la vidéo de fond" diff --git a/src/i18n/ui/it.json b/src/i18n/ui/it.json index a591f6a9ca..fe7f9532d5 100644 --- a/src/i18n/ui/it.json +++ b/src/i18n/ui/it.json @@ -1,11 +1,11 @@ { "home": { "welcome": "Benvenuto", - "workInProgress": "Questa è una homepage in fase di sviluppo.", + "workInProgress": "Questa è una homepage di work-in-progress.", "reviewDesignSystem": { - "prefix": "Consulta la", - "link": "Base del Design System", - "suffix": "pagina demo per esplorare tutti i token, le primitive e i pattern." + "prefix": "Rivedi la", + "link": "Design System Foundations", + "suffix": "pagina demo per esplorare tutti i gettoni, primitive e modelli." } }, "search": { @@ -13,19 +13,16 @@ "ariaLabel": "Inizia a digitare per cercare" }, "theme": { - "toggle": "Cambia tema", - "switchToLight": "Passa alla modalità chiara", + "toggle": "Attiva/Disattiva tema", + "switchToLight": "Passa alla modalità luce", "switchToDark": "Passa alla modalità scura" }, "version": { "selectLabel": "Seleziona la versione API" }, - "language": { - "selectLabel": "Seleziona lingua" - }, "nav": { "mainMenu": "Menu principale", - "toggleMenu": "Mostra/Nascondi menu", + "toggleMenu": "Attiva/disattiva menu", "home": "home", "breadcrumb": "Breadcrumb", "mainNavigation": "Navigazione principale", @@ -33,16 +30,16 @@ }, "menu": { "main": { - "docs": "Documentazione", + "docs": "Documenti", "api": "API", "resources": "Risorse", "blog": "Blog", "support": "Supporto" }, "sections": { - "gettingStarted": "Primi passi", + "gettingStarted": "Per iniziare", "guide": "Guida", - "migration": "Guide alla migrazione", + "migration": "Guide di migrazione", "advanced": "Argomenti avanzati", "express": "express()", "application": "Applicazione", @@ -53,27 +50,27 @@ }, "items": { "installing": "Installazione", - "helloWorld": "Hello world", - "expressGenerator": "Generatore Express", - "basicRouting": "Routing di base", + "helloWorld": "Ciao mondo", + "expressGenerator": "Generatore espresso", + "basicRouting": "Instradamento base", "staticFiles": "Servire file statici", "examples": "Esempi", "faq": "FAQ", "routing": "Routing", - "writingMiddleware": "Scrivere middleware", + "writingMiddleware": "Scrittura middleware", "usingMiddleware": "Usare middleware", - "usingTemplateEngines": "Usare template engines", + "usingTemplateEngines": "Utilizzo di modelli di motori", "errorHandling": "Gestione errori", - "debugging": "Debugging", - "behindProxies": "Dietro i proxy", + "debugging": "Debug", + "behindProxies": "Dietro proxy", "databaseIntegration": "Integrazione database", - "overridingExpressApi": "Sovrascrivere API di Express", - "migratingTo4": "Migrazione a Express 4", - "migratingTo5": "Migrazione a Express 5", - "buildingTemplateEngines": "Creare template engines", - "bestPracticePerformance": "Best practice di performance", - "bestPracticeSecurity": "Best practice di sicurezza", - "healthcheckGracefulShutdown": "Health check & spegnimento graduale", + "overridingExpressApi": "Sovrascrivendo l'API Express", + "migratingTo4": "Passaggio a Express 4", + "migratingTo5": "Passaggio a Express 5", + "buildingTemplateEngines": "Motori modello di costruzione", + "bestPracticePerformance": "Migliori pratiche di prestazione", + "bestPracticeSecurity": "Migliori pratiche di sicurezza", + "healthcheckGracefulShutdown": "Controlli di salute & spegnimento aggraziato", "securityUpdates": "Aggiornamenti di sicurezza", "overview": "Panoramica", "properties": "Proprietà", @@ -81,9 +78,9 @@ "events": "Eventi", "types": "Integrato", "community": "Community", - "glossary": "Glossario", + "glossary": "Glossary", "contributing": "Contribuire", - "utils": "Utility", + "utils": "Utilità", "middleware": "Middleware" }, "aria": { @@ -92,36 +89,36 @@ "resources": "Risorse", "blog": "Blog", "support": "Supporto", - "installing": "Installare Express", - "helloWorld": "Esempio Hello world", - "expressGenerator": "Generatore Express", - "routing": "Guida al routing", - "writingMiddleware": "Guida alla scrittura di middleware", - "usingMiddleware": "Guida all’uso di middleware", - "usingTemplateEngines": "Guida all’uso dei template engines", - "errorHandling": "Guida alla gestione degli errori", - "debugging": "Debugging di Express", - "behindProxies": "Express dietro i proxy", - "databaseIntegration": "Guida all’integrazione database", - "overridingExpressApi": "Guida alla sovrascrittura API di Express", - "application": "Panoramica applicazione", + "installing": "Installazione Di Express", + "helloWorld": "Ciao esempio mondiale", + "expressGenerator": "Generatore espresso", + "routing": "Guida di routing", + "writingMiddleware": "Scrittura guida middleware", + "usingMiddleware": "Utilizzo della guida middleware", + "usingTemplateEngines": "Utilizzo guida motori modello", + "errorHandling": "Guida gestione errori", + "debugging": "Debug Express", + "behindProxies": "Espresso dietro i proxy", + "databaseIntegration": "Guida all'integrazione del database", + "overridingExpressApi": "Superare la guida API di Express", + "application": "Panoramica dell'applicazione", "request": "Panoramica richiesta", - "response": "Panoramica risposta", - "router": "Panoramica router", - "middleware": "Risorse middleware", - "community": "Risorse community", - "glossary": "Glossario termini", + "response": "Panoramica delle risposte", + "router": "Panoramica del router", + "middleware": "Risorse Middleware", + "community": "Risorse comunitarie", + "glossary": "Glossario dei termini", "contributing": "Guida al contributo", - "utils": "Utility" + "utils": "Utilità" } }, "doc": { "previousPage": "Precedente", "nextPage": "Successivo", - "pageNavigation": "Navigazione pagina" + "pageNavigation": "Page navigation" }, "page": { - "editOnGitHub": "Modifica su GitHub", + "editOnGitHub": "Edit on GitHub", "translateThis": "Traduci questa pagina" }, "post": { @@ -137,7 +134,7 @@ "linkCopied": "Link copiato!", "toc": "Su questa pagina", "more": "Altro da Express", - "writeBanner": "Vuoi scrivere un post?\nConsulta le nostre linee guida per iniziare.", + "writeBanner": "Sei interessato a scrivere un post? \n Scopri le nostre linee guida per iniziare.", "writeGuidelines": "Leggi le linee guida" }, "toc": { @@ -146,33 +143,33 @@ "features": { "title": "Chiarezza sulla complessità. Per ogni sviluppatore.", "performance": { - "title": "Performance", - "body": "Express fornisce uno strato leggero di funzionalità web fondamentali senza nascondere le caratteristiche di Node.js." + "title": "Prestazioni", + "body": "Express fornisce un sottile strato di funzionalità di applicazione web fondamentali, senza oscurare le caratteristiche di Node.js che conoscete e amate." }, "api": { "title": "API", - "body": "Con numerosi metodi HTTP e middleware, creare un’API robusta è rapido e semplice." + "body": "Con una miriade di metodi di utilità HTTP e middleware a vostra disposizione, la creazione di un'API robusta è facile e veloce." }, "middleware": { "title": "Middleware", - "body": "Express è un framework leggero e flessibile che può essere esteso tramite middleware." + "body": "Express è un framework di routing leggero e flessibile con caratteristiche essenziali minimali che devono essere aumentate attraverso l'uso di moduli middleware Express." }, "webapplication": { "title": "Applicazioni Web", - "body": "Express è un framework minimale e flessibile per applicazioni web e mobile." + "body": "Express è un framework di applicazioni web di Node.js minimale e flessibile che fornisce un insieme robusto di funzionalità per applicazioni web e mobili." } }, "error404": { - "title": "404 - Pagina non trovata", + "title": "404 - Pagina Non Trovata", "description": "La pagina che stai cercando non è stata trovata.", - "heading": "Pagina non trovata", - "message": "La pagina non esiste o è stata spostata.", - "goHome": "Vai alla Home" + "heading": "Pagina Non Trovata", + "message": "La pagina che stai cercando non esiste o è stata spostata.", + "goHome": "Vai a Home" }, "hero": { - "tagline": "Framework web veloce e minimale per Node.js", - "getStarted": "Inizia", - "videoPause": "Metti in pausa il video di sfondo", - "videoPlay": "Riproduci il video di sfondo" + "tagline": "Quadro web veloce, senza pareri, minimalista per Node.js", + "getStarted": "Per Iniziare", + "videoPause": "Pausa video in background", + "videoPlay": "Riproduci video in background" } } diff --git a/src/i18n/ui/ja.json b/src/i18n/ui/ja.json index 21fae5d187..143632500b 100644 --- a/src/i18n/ui/ja.json +++ b/src/i18n/ui/ja.json @@ -1,31 +1,28 @@ { "home": { "welcome": "ようこそ", - "workInProgress": "これは作業中のホームページです。", + "workInProgress": "これは進行中のホームページです。", "reviewDesignSystem": { - "prefix": "以下を確認してください：", - "link": "デザインシステムの基礎", - "suffix": "デモページで全てのトークン、プリミティブ、パターンを確認できます。" + "prefix": "レビュー：", + "link": "デザインシステム基礎", + "suffix": "すべてのトークン、プリミティブ、パターンを調べるデモページ。" } }, "search": { "placeholder": "入力を開始...", - "ariaLabel": "検索するには入力してください" + "ariaLabel": "検索を開始する" }, "theme": { - "toggle": "テーマ切り替え", - "switchToLight": "ライトモードに切替", - "switchToDark": "ダークモードに切替" + "toggle": "テーマの切り替え", + "switchToLight": "ライトモードに切り替える", + "switchToDark": "ダークモードに切り替える" }, "version": { - "selectLabel": "APIバージョンを選択" - }, - "language": { - "selectLabel": "言語を選択" + "selectLabel": "API バージョンを選択" }, "nav": { "mainMenu": "メインメニュー", - "toggleMenu": "メニューを切替", + "toggleMenu": "切り替えメニュー", "home": "ホーム", "breadcrumb": "パンくずリスト", "mainNavigation": "メインナビゲーション", @@ -42,47 +39,47 @@ "sections": { "gettingStarted": "はじめに", "guide": "ガイド", - "migration": "マイグレーションガイド", + "migration": "移行ガイド", "advanced": "高度なトピック", "express": "express()", "application": "アプリケーション", "request": "リクエスト", - "response": "レスポンス", - "router": "ルーター", + "response": "回答", + "router": "Router", "middleware": "ミドルウェア" }, "items": { - "installing": "インストール", + "installing": "インストール中", "helloWorld": "Hello world", - "expressGenerator": "Expressジェネレーター", + "expressGenerator": "Express generator", "basicRouting": "基本ルーティング", - "staticFiles": "静的ファイル提供", + "staticFiles": "静的ファイルを提供中", "examples": "例", "faq": "FAQ", "routing": "ルーティング", - "writingMiddleware": "ミドルウェア作成", - "usingMiddleware": "ミドルウェア使用", - "usingTemplateEngines": "テンプレートエンジン使用", + "writingMiddleware": "ミドルウェアの書き込み", + "usingMiddleware": "ミドルウェアの使用", + "usingTemplateEngines": "テンプレートエンジンの使用", "errorHandling": "エラー処理", "debugging": "デバッグ", - "behindProxies": "プロキシの背後", - "databaseIntegration": "データベース統合", - "overridingExpressApi": "Express APIの上書き", - "migratingTo4": "Express 4への移行", - "migratingTo5": "Express 5への移行", - "buildingTemplateEngines": "テンプレートエンジン作成", - "bestPracticePerformance": "パフォーマンスベストプラクティス", - "bestPracticeSecurity": "セキュリティベストプラクティス", - "healthcheckGracefulShutdown": "ヘルスチェック & 優雅なシャットダウン", - "securityUpdates": "セキュリティアップデート", + "behindProxies": "プロキシの背後にある", + "databaseIntegration": "データベースの統合", + "overridingExpressApi": "Express API のオーバーライド", + "migratingTo4": "Express 4に移動中", + "migratingTo5": "Express 5に移動中", + "buildingTemplateEngines": "ビルディングテンプレートエンジン", + "bestPracticePerformance": "パフォーマンスのベストプラクティス", + "bestPracticeSecurity": "セキュリティのベストプラクティス", + "healthcheckGracefulShutdown": "ヘルスチェックと優雅な停止", + "securityUpdates": "セキュリティの更新", "overview": "概要", - "properties": "プロパティ", + "properties": "プロパティー", "methods": "メソッド", "events": "イベント", - "types": "組み込み", + "types": "ビルトイン", "community": "コミュニティ", - "glossary": "用語集", - "contributing": "貢献", + "glossary": "Glossary", + "contributing": "コントリビューション", "utils": "ユーティリティ", "middleware": "ミドルウェア" }, @@ -92,23 +89,23 @@ "resources": "リソース", "blog": "ブログ", "support": "サポート", - "installing": "Expressをインストール", - "helloWorld": "Hello world例", - "expressGenerator": "Expressジェネレーター", + "installing": "Express のインストール", + "helloWorld": "Hello world example", + "expressGenerator": "Express generator", "routing": "ルーティングガイド", - "writingMiddleware": "ミドルウェア作成ガイド", - "usingMiddleware": "ミドルウェア使用ガイド", - "usingTemplateEngines": "テンプレートエンジンガイド", - "errorHandling": "エラー処理ガイド", - "debugging": "Expressデバッグ", - "behindProxies": "プロキシ背後のExpress", + "writingMiddleware": "ミドルウェアガイドを書く", + "usingMiddleware": "ミドルウェアガイドの使用", + "usingTemplateEngines": "テンプレートエンジンガイドの使用", + "errorHandling": "ガイドの処理中にエラー", + "debugging": "Expressのデバッグ", + "behindProxies": "プロキシの背後にあるエクスプレス", "databaseIntegration": "データベース統合ガイド", - "overridingExpressApi": "Express API上書きガイド", - "application": "アプリケーション概要", - "request": "リクエスト概要", - "response": "レスポンス概要", - "router": "ルーター概要", - "middleware": "ミドルウェアリソース", + "overridingExpressApi": "Express API ガイドをオーバーライド", + "application": "アプリケーションの概要", + "request": "要求の概要", + "response": "応答の概要", + "router": "ルーターの概要", + "middleware": "ミドルウェアのリソース", "community": "コミュニティリソース", "glossary": "用語集", "contributing": "貢献ガイド", @@ -116,63 +113,63 @@ } }, "doc": { - "previousPage": "前へ", + "previousPage": "前", "nextPage": "次へ", - "pageNavigation": "ページナビゲーション" + "pageNavigation": "Page navigation" }, "page": { - "editOnGitHub": "GitHubで編集", + "editOnGitHub": "Edit on GitHub", "translateThis": "このページを翻訳" }, "post": { "share": "共有", - "shareOnX": "Xで共有", + "shareOnX": "X上で共有", "shareOnBluesky": "Blueskyで共有", "shareOnLinkedIn": "LinkedInで共有", - "shareOnSlack": "Slackで共有", + "shareOnSlack": "Slack で共有", "shareOnTelegram": "Telegramで共有", "shareOnWhatsApp": "WhatsAppで共有", - "rssFeed": "RSSフィード", + "rssFeed": "RSS フィード", "copyLink": "リンクをコピー", "linkCopied": "リンクをコピーしました！", - "toc": "このページ内", - "more": "Expressからもっと", - "writeBanner": "投稿を書きたいですか？\nガイドラインを確認して始めましょう。", + "toc": "このページ", + "more": "エクスプレスからもっと見る", + "writeBanner": "投稿を書くことに興味がありますか？ \n 私たちのガイドラインをチェックして始めましょう。", "writeGuidelines": "ガイドラインを読む" }, "toc": { "overview": "概要" }, "features": { - "title": "複雑さよりも明快さ。すべての開発者のために。", + "title": "複雑性より明快です。すべての開発者にとって。", "performance": { "title": "パフォーマンス", - "body": "Expressは基本的なWebアプリ機能の薄いレイヤーを提供し、Node.jsの機能を隠しません。" + "body": "Express は基本的な Web アプリケーション機能の薄い層を提供しますが、Node.js の機能を不明瞭にすることはありません。" }, "api": { "title": "API", - "body": "多くのHTTPユーティリティやミドルウェアで、堅牢なAPI作成が迅速かつ簡単です。" + "body": "無数のHTTPユーティリティメソッドとミドルウェアを自由に使えば、堅牢なAPIを簡単かつ迅速に作成できます。" }, "middleware": { "title": "ミドルウェア", - "body": "Expressは軽量で柔軟なルーティングフレームワークで、ミドルウェアモジュールを使って拡張可能です。" + "body": "Expressは軽量で柔軟なルーティングフレームワークで、最小限のコア機能を備え、Expressミドルウェアモジュールを使用して拡張します。" }, "webapplication": { "title": "Webアプリケーション", - "body": "ExpressはWeb・モバイルアプリ向けの最小かつ柔軟なNode.jsフレームワークです。" + "body": "Express は最小限かつ柔軟な Node.js の Web アプリケーションフレームワークで、Web およびモバイル アプリケーションに堅牢な一連の機能を提供します。" } }, "error404": { "title": "404 - ページが見つかりません", - "description": "お探しのページは見つかりませんでした。", + "description": "お探しのページが見つかりませんでした。", "heading": "ページが見つかりません", - "message": "ページが存在しないか、移動されました。", - "goHome": "ホームに戻る" + "message": "お探しのページは存在しないか、移動されています。", + "goHome": "ホームへ移動" }, "hero": { - "tagline": "Node.js向けの高速で最小限のWebフレームワーク", - "getStarted": "はじめる", - "videoPause": "背景動画を一時停止", - "videoPlay": "背景動画を再生" + "tagline": "Node.jsの高速、非公開、最小限のWebフレームワーク", + "getStarted": "はじめよう", + "videoPause": "背景ビデオを一時停止", + "videoPlay": "背景ビデオを再生" } } diff --git a/src/i18n/ui/ko.json b/src/i18n/ui/ko.json index 894c11837f..5a085e2a46 100644 --- a/src/i18n/ui/ko.json +++ b/src/i18n/ui/ko.json @@ -1,178 +1,175 @@ { "home": { - "welcome": "환영합니다", - "workInProgress": "이 페이지는 작업 중인 홈페이지입니다.", + "welcome": "Welcome", + "workInProgress": "This is a work-in-progress homepage.", "reviewDesignSystem": { - "prefix": "다음 페이지를 확인하세요:", - "link": "디자인 시스템 기초", - "suffix": "데모 페이지에서 모든 토큰, 프리미티브 및 패턴을 탐색할 수 있습니다." + "prefix": "Review the", + "link": "Design System Foundations", + "suffix": "demo page to explore all tokens, primitives, and patterns." } }, "search": { - "placeholder": "입력 시작...", - "ariaLabel": "검색하려면 입력하세요" + "placeholder": "Start typing...", + "ariaLabel": "Start typing to search" }, "theme": { - "toggle": "테마 전환", - "switchToLight": "라이트 모드로 전환", - "switchToDark": "다크 모드로 전환" + "toggle": "Toggle theme", + "switchToLight": "Switch to light mode", + "switchToDark": "Switch to dark mode" }, "version": { - "selectLabel": "API 버전 선택" - }, - "language": { - "selectLabel": "언어 선택" + "selectLabel": "Select API version" }, "nav": { - "mainMenu": "메인 메뉴", - "toggleMenu": "메뉴 전환", - "home": "홈", - "breadcrumb": "브레드크럼", - "mainNavigation": "메인 내비게이션", - "selectVersion": "문서 버전 선택" + "mainMenu": "Main menu", + "toggleMenu": "Toggle menu", + "home": "home", + "breadcrumb": "Breadcrumb", + "mainNavigation": "Main navigation", + "selectVersion": "Select documentation version" }, "menu": { "main": { - "docs": "문서", + "docs": "Docs", "api": "API", - "resources": "리소스", - "blog": "블로그", - "support": "지원" + "resources": "Resources", + "blog": "Blog", + "support": "Support" }, "sections": { - "gettingStarted": "시작하기", - "guide": "가이드", - "migration": "마이그레이션 가이드", - "advanced": "고급 주제", + "gettingStarted": "Getting started", + "guide": "Guide", + "migration": "Migration guides", + "advanced": "Advanced topics", "express": "express()", - "application": "애플리케이션", - "request": "요청", - "response": "응답", - "router": "라우터", - "middleware": "미들웨어" + "application": "Application", + "request": "Request", + "response": "Response", + "router": "Router", + "middleware": "Middleware" }, "items": { - "installing": "설치", + "installing": "Installing", "helloWorld": "Hello world", - "expressGenerator": "Express 생성기", - "basicRouting": "기본 라우팅", - "staticFiles": "정적 파일 제공", - "examples": "예제", + "expressGenerator": "Express generator", + "basicRouting": "Basic routing", + "staticFiles": "Serving static files", + "examples": "Examples", "faq": "FAQ", - "routing": "라우팅", - "writingMiddleware": "미들웨어 작성", - "usingMiddleware": "미들웨어 사용", - "usingTemplateEngines": "템플릿 엔진 사용", - "errorHandling": "오류 처리", - "debugging": "디버깅", - "behindProxies": "프록시 뒤", - "databaseIntegration": "데이터베이스 통합", - "overridingExpressApi": "Express API 재정의", - "migratingTo4": "Express 4로 이전", - "migratingTo5": "Express 5로 이전", - "buildingTemplateEngines": "템플릿 엔진 구축", - "bestPracticePerformance": "성능 모범 사례", - "bestPracticeSecurity": "보안 모범 사례", - "healthcheckGracefulShutdown": "헬스체크 및 점진적 종료", - "securityUpdates": "보안 업데이트", - "overview": "개요", - "properties": "속성", - "methods": "메서드", - "events": "이벤트", - "types": "내장", - "community": "커뮤니티", - "glossary": "용어집", - "contributing": "기여", - "utils": "유틸리티", - "middleware": "미들웨어" + "routing": "Routing", + "writingMiddleware": "Writing middleware", + "usingMiddleware": "Using middleware", + "usingTemplateEngines": "Using template engines", + "errorHandling": "Error handling", + "debugging": "Debugging", + "behindProxies": "Behind proxies", + "databaseIntegration": "Database integration", + "overridingExpressApi": "Overriding the Express API", + "migratingTo4": "Moving to Express 4", + "migratingTo5": "Moving to Express 5", + "buildingTemplateEngines": "Building template engines", + "bestPracticePerformance": "Performance best practices", + "bestPracticeSecurity": "Security best practices", + "healthcheckGracefulShutdown": "Health checks & graceful shutdown", + "securityUpdates": "Security updates", + "overview": "Overview", + "properties": "Properties", + "methods": "Methods", + "events": "Events", + "types": "Built-in", + "community": "Community", + "glossary": "Glossary", + "contributing": "Contributing", + "utils": "Utilities", + "middleware": "Middleware" }, "aria": { - "docs": "문서", - "api": "API 참고", - "resources": "리소스", - "blog": "블로그", - "support": "지원", - "installing": "Express 설치", - "helloWorld": "Hello world 예제", - "expressGenerator": "Express 생성기", - "routing": "라우팅 가이드", - "writingMiddleware": "미들웨어 작성 가이드", - "usingMiddleware": "미들웨어 사용 가이드", - "usingTemplateEngines": "템플릿 엔진 사용 가이드", - "errorHandling": "오류 처리 가이드", - "debugging": "Express 디버깅", - "behindProxies": "프록시 뒤의 Express", - "databaseIntegration": "데이터베이스 통합 가이드", - "overridingExpressApi": "Express API 재정의 가이드", - "application": "애플리케이션 개요", - "request": "요청 개요", - "response": "응답 개요", - "router": "라우터 개요", - "middleware": "미들웨어 리소스", - "community": "커뮤니티 리소스", - "glossary": "용어집", - "contributing": "기여 가이드", - "utils": "유틸리티" + "docs": "Documentation", + "api": "API Reference", + "resources": "Resources", + "blog": "Blog", + "support": "Support", + "installing": "Installing Express", + "helloWorld": "Hello world example", + "expressGenerator": "Express generator", + "routing": "Routing guide", + "writingMiddleware": "Writing middleware guide", + "usingMiddleware": "Using middleware guide", + "usingTemplateEngines": "Using template engines guide", + "errorHandling": "Error handling guide", + "debugging": "Debugging Express", + "behindProxies": "Express behind proxies", + "databaseIntegration": "Database integration guide", + "overridingExpressApi": "Overriding the Express API guide", + "application": "Application overview", + "request": "Request overview", + "response": "Response overview", + "router": "Router overview", + "middleware": "Middleware resources", + "community": "Community resources", + "glossary": "Glossary of terms", + "contributing": "Contributing guide", + "utils": "Utilities" } }, "doc": { - "previousPage": "이전", - "nextPage": "다음", - "pageNavigation": "페이지 내비게이션" + "previousPage": "Previous", + "nextPage": "Next", + "pageNavigation": "Page navigation" }, "page": { - "editOnGitHub": "GitHub에서 편집", - "translateThis": "이 페이지 번역" + "editOnGitHub": "Edit on GitHub", + "translateThis": "Translate this page" }, "post": { - "share": "공유", - "shareOnX": "X에서 공유", - "shareOnBluesky": "Bluesky에서 공유", - "shareOnLinkedIn": "LinkedIn에서 공유", - "shareOnSlack": "Slack에서 공유", - "shareOnTelegram": "Telegram에서 공유", - "shareOnWhatsApp": "WhatsApp에서 공유", - "rssFeed": "RSS 피드", - "copyLink": "링크 복사", - "linkCopied": "링크가 복사되었습니다!", - "toc": "이 페이지에서", - "more": "Express 더 보기", - "writeBanner": "게시글을 작성하고 싶나요?\n가이드라인을 확인하고 시작하세요.", - "writeGuidelines": "가이드라인 읽기" + "share": "Share", + "shareOnX": "Share on X", + "shareOnBluesky": "Share on Bluesky", + "shareOnLinkedIn": "Share on LinkedIn", + "shareOnSlack": "Share on Slack", + "shareOnTelegram": "Share on Telegram", + "shareOnWhatsApp": "Share on WhatsApp", + "rssFeed": "RSS Feed", + "copyLink": "Copy link", + "linkCopied": "Link copied!", + "toc": "On this page", + "more": "More from Express", + "writeBanner": "Interested in writing a post? \n Check out our guidelines to get started.", + "writeGuidelines": "Read the guidelines" }, "toc": { - "overview": "개요" + "overview": "Overview" }, "features": { - "title": "복잡함보다 명확함. 모든 개발자를 위해.", + "title": "Clarity over complexity. For every developer.", "performance": { - "title": "성능", - "body": "Express는 Node.js 기능을 숨기지 않고 웹 애플리케이션의 기본 기능만을 제공하는 얇은 레이어를 제공합니다." + "title": "Performance", + "body": "Express provides a thin layer of fundamental web application features, without obscuring Node.js features that you know and love." }, "api": { - "title": "API", - "body": "다양한 HTTP 유틸리티와 미들웨어를 사용하면 견고한 API를 빠르고 쉽게 만들 수 있습니다." + "title": "APIs", + "body": "With a myriad of HTTP utility methods and middleware at your disposal, creating a robust API is quick and easy." }, "middleware": { - "title": "미들웨어", - "body": "Express는 최소한의 핵심 기능을 가진 가벼운 라우팅 프레임워크로, 미들웨어 모듈을 통해 확장할 수 있습니다." + "title": "Middleware", + "body": "Express is a lightweight and flexible routing framework with minimal core features meant to be augmented through the use of Express middleware modules." }, "webapplication": { - "title": "웹 애플리케이션", - "body": "Express는 웹 및 모바일 애플리케이션을 위한 최소하고 유연한 Node.js 웹 프레임워크입니다." + "title": "Web Applications", + "body": "Express is a minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications." } }, "error404": { - "title": "404 - 페이지를 찾을 수 없음", - "description": "요청하신 페이지를 찾을 수 없습니다.", - "heading": "페이지를 찾을 수 없음", - "message": "페이지가 존재하지 않거나 이동되었습니다.", - "goHome": "홈으로 이동" + "title": "404 - Page Not Found", + "description": "The page you are looking for could not be found.", + "heading": "Page Not Found", + "message": "The page you are looking for does not exist or has been moved.", + "goHome": "Go to Home" }, "hero": { - "tagline": "Node.js를 위한 빠르고 최소한의 웹 프레임워크", - "getStarted": "시작하기", - "videoPause": "배경 영상 일시정지", - "videoPlay": "배경 영상 재생" + "tagline": "Fast, unopinionated, minimalist web framework for Node.js", + "getStarted": "Get Started", + "videoPause": "Pause background video", + "videoPlay": "Play background video" } } diff --git a/src/i18n/ui/pt-br.json b/src/i18n/ui/pt-br.json index 1781abdb15..721361c1e8 100644 --- a/src/i18n/ui/pt-br.json +++ b/src/i18n/ui/pt-br.json @@ -1,11 +1,11 @@ { "home": { - "welcome": "Bem-vindo", - "workInProgress": "Esta é uma página inicial em desenvolvimento.", + "welcome": "Boas-vindas", + "workInProgress": "Esta é uma página inicial em progresso.", "reviewDesignSystem": { - "prefix": "Revise a", - "link": "Base do Design System", - "suffix": "página de demonstração para explorar todos os tokens, primitivas e padrões." + "prefix": "Revisar o", + "link": "Criar Fundamentos de Sistema", + "suffix": "página demo para explorar todos os tokens, primitivos e padrões." } }, "search": { @@ -14,114 +14,111 @@ }, "theme": { "toggle": "Alternar tema", - "switchToLight": "Mudar para modo claro", - "switchToDark": "Mudar para modo escuro" + "switchToLight": "Alternar para o modo claro", + "switchToDark": "Mudar para o modo escuro" }, "version": { "selectLabel": "Selecionar versão da API" }, - "language": { - "selectLabel": "Selecionar idioma" - }, "nav": { "mainMenu": "Menu principal", - "toggleMenu": "Alternar menu", - "home": "início", - "breadcrumb": "Breadcrumb", + "toggleMenu": "Abrir/fechar menu", + "home": "casa", + "breadcrumb": "Trilha", "mainNavigation": "Navegação principal", "selectVersion": "Selecionar versão da documentação" }, "menu": { "main": { - "docs": "Documentos", + "docs": "Documentação", "api": "API", "resources": "Recursos", - "blog": "Blog", - "support": "Suporte" + "blog": "Blogue", + "support": "SUPORTE" }, "sections": { - "gettingStarted": "Introdução", + "gettingStarted": "Primeiros Passos", "guide": "Guia", "migration": "Guias de migração", "advanced": "Tópicos avançados", "express": "express()", - "application": "Aplicação", - "request": "Requisição", + "application": "Solicitação", + "request": "Pedir", "response": "Resposta", "router": "Roteador", - "middleware": "Middleware" + "middleware": "Mediador" }, "items": { "installing": "Instalando", - "helloWorld": "Hello world", - "expressGenerator": "Gerador Express", + "helloWorld": "Olá, mundo", + "expressGenerator": "Gerador expresso", "basicRouting": "Roteamento básico", "staticFiles": "Servindo arquivos estáticos", "examples": "Exemplos", - "faq": "FAQ", + "faq": "Perguntas Frequentes", "routing": "Roteamento", "writingMiddleware": "Escrevendo middleware", - "usingMiddleware": "Usando middleware", - "usingTemplateEngines": "Usando motores de template", - "errorHandling": "Tratamento de erros", + "usingMiddleware": "Usando o middleware", + "usingTemplateEngines": "Usando motores de modelos", + "errorHandling": "Manipulação de erros", "debugging": "Depuração", - "behindProxies": "Por trás de proxies", - "databaseIntegration": "Integração com banco de dados", - "overridingExpressApi": "Substituindo a API do Express", - "migratingTo4": "Migrando para Express 4", - "migratingTo5": "Migrando para Express 5", - "buildingTemplateEngines": "Criando motores de template", - "bestPracticePerformance": "Melhores práticas de performance", + "behindProxies": "Atrás dos proxies", + "databaseIntegration": "Integração com base de dados", + "overridingExpressApi": "Sobrescrevendo a API Expresso", + "migratingTo4": "Mover para Expresso 4", + "migratingTo5": "Movendo para Expresso 5", + "buildingTemplateEngines": "Mecanismos de construção", + "bestPracticePerformance": "Melhores práticas de desempenho", "bestPracticeSecurity": "Melhores práticas de segurança", - "healthcheckGracefulShutdown": "Health checks & encerramento gracioso", + "healthcheckGracefulShutdown": "Verificações de saúde e desligamento gracioso", "securityUpdates": "Atualizações de segurança", - "overview": "Visão geral", - "properties": "Propriedades", + "overview": "Geral", + "properties": "propriedades", "methods": "Métodos", "events": "Eventos", - "types": "Integrado", + "types": "Internos", "community": "Comunidade", - "glossary": "Glossário", - "contributing": "Contribuindo", - "utils": "Utilitários", - "middleware": "Middleware" + "glossary": "Glossary", + "contributing": "Contribuições", + "utils": "Serviços", + "middleware": "Mediador" }, "aria": { "docs": "Documentação", "api": "Referência de API", "resources": "Recursos", - "blog": "Blog", - "support": "Suporte", - "installing": "Instalando Express", - "helloWorld": "Exemplo Hello world", - "expressGenerator": "Gerador Express", + "blog": "Blogue", + "support": "SUPORTE", + "installing": "Instalando o Express", + "helloWorld": "Olá, exemplo do mundo", + "expressGenerator": "Gerador expresso", "routing": "Guia de roteamento", - "writingMiddleware": "Guia de escrita de middleware", - "usingMiddleware": "Guia de uso de middleware", - "usingTemplateEngines": "Guia de uso de motores de template", - "errorHandling": "Guia de tratamento de erros", - "debugging": "Depurando Express", - "behindProxies": "Express atrás de proxies", - "databaseIntegration": "Guia de integração com banco de dados", - "overridingExpressApi": "Guia de substituição da API do Express", - "application": "Visão geral da aplicação", - "request": "Visão geral da requisição", - "response": "Visão geral da resposta", + "writingMiddleware": "Escrevendo o guia middleware", + "usingMiddleware": "Usando guia de middleware", + "usingTemplateEngines": "Usando guia de motores de modelos", + "errorHandling": "Guia para manipulação de erros", + "debugging": "Expresso de depuração", + "behindProxies": "Expresso atrás dos proxies", + "databaseIntegration": "Guia de integração do banco", + "overridingExpressApi": "Sobrescrevendo o guia API Expresso", + "application": "Resumo do aplicativo", + "request": "Solicitar resumo", + "response": "Resumo da resposta", "router": "Visão geral do roteador", - "middleware": "Recursos de middleware", - "community": "Recursos da comunidade", + "middleware": "Recursos do Mediador", + "community": "Recursos da Comunidade", "glossary": "Glossário de termos", - "contributing": "Guia de contribuição", - "utils": "Utilitários" + "contributing": "Guia contribuidor", + "utils": "Serviços" } }, "doc": { "previousPage": "Anterior", - "nextPage": "Próxima", - "pageNavigation": "Navegação da página" + "nextPage": "Próximo", + "pageNavigation": "Page navigation" }, "page": { - "editOnGitHub": "Editar no GitHub", + "editOnGitHub": "Edit on GitHub", "translateThis": "Traduzir esta página" }, "post": { @@ -131,48 +128,48 @@ "shareOnLinkedIn": "Compartilhar no LinkedIn", "shareOnSlack": "Compartilhar no Slack", "shareOnTelegram": "Compartilhar no Telegram", - "shareOnWhatsApp": "Compartilhar no WhatsApp", + "shareOnWhatsApp": "Compartilhe no WhatsApp", "rssFeed": "Feed RSS", - "copyLink": "Copiar link", + "copyLink": "Link de cópia", "linkCopied": "Link copiado!", "toc": "Nesta página", "more": "Mais do Express", - "writeBanner": "Interessado em escrever um post?\nConfira nossas diretrizes para começar.", + "writeBanner": "Interessou-se em escrever uma publicação? U \n Confira nossas diretrizes para começar.", "writeGuidelines": "Leia as diretrizes" }, "toc": { - "overview": "Visão geral" + "overview": "Geral" }, "features": { - "title": "Clareza sobre complexidade. Para todos os desenvolvedores.", + "title": "Clareza sobre complexidade. Para cada desenvolvedor.", "performance": { - "title": "Performance", - "body": "O Express fornece uma camada fina de recursos fundamentais para aplicações web, sem esconder recursos do Node.js." + "title": "Desempenho", + "body": "Expresso fornece uma fina camada de recursos fundamentais de aplicativos web, sem obscurecer recursos de Node.js que você conhece e ama." }, "api": { "title": "APIs", - "body": "Com diversos métodos HTTP e middleware, criar uma API robusta é rápido e fácil." + "body": "Com uma miríade de métodos de utilitário HTTP e middleware à sua disposição, criar uma API robusta é rápido e fácil." }, "middleware": { - "title": "Middleware", - "body": "O Express é um framework de roteamento leve e flexível, com recursos mínimos que podem ser estendidos via módulos de middleware." + "title": "Mediador", + "body": "Expresso é um framework de roteamento leve e flexível com recursos básicos mínimos destinados a serem aumentados através do uso de módulos de middleware Express." }, "webapplication": { - "title": "Aplicações Web", - "body": "O Express é um framework Node.js mínimo e flexível para aplicações web e mobile." + "title": "Aplicativos Web", + "body": "Expresso é um framework de aplicativos web Node.js mínimo e flexível que fornece um conjunto robusto de recursos para aplicativos web e móveis." } }, "error404": { "title": "404 - Página não encontrada", - "description": "A página que você procura não foi encontrada.", + "description": "A página que você está procurando não pôde ser encontrada.", "heading": "Página não encontrada", - "message": "A página não existe ou foi movida.", - "goHome": "Ir para a página inicial" + "message": "A página que você procura não existe ou foi movida.", + "goHome": "Ir para o início" }, "hero": { - "tagline": "Framework web rápido e minimalista para Node.js", - "getStarted": "Começar", - "videoPause": "Pausar vídeo de fundo", + "tagline": "Framework web para Node.js rápido, não opinionizado e minimalista", + "getStarted": "Comece Agora", + "videoPause": "Pausar vídeo em segundo plano", "videoPlay": "Reproduzir vídeo de fundo" } } diff --git a/src/i18n/ui/zh-tw.json b/src/i18n/ui/zh-tw.json index 4d6d065cb3..5a085e2a46 100644 --- a/src/i18n/ui/zh-tw.json +++ b/src/i18n/ui/zh-tw.json @@ -1,178 +1,175 @@ { "home": { - "welcome": "欢迎", - "workInProgress": "这是正在开发中的主页。", + "welcome": "Welcome", + "workInProgress": "This is a work-in-progress homepage.", "reviewDesignSystem": { - "prefix": "查看", - "link": "设计系统基础", - "suffix": "演示页面以探索所有令牌、原语和模式。" + "prefix": "Review the", + "link": "Design System Foundations", + "suffix": "demo page to explore all tokens, primitives, and patterns." } }, "search": { - "placeholder": "开始输入...", - "ariaLabel": "开始输入以搜索" + "placeholder": "Start typing...", + "ariaLabel": "Start typing to search" }, "theme": { - "toggle": "切換主題", - "switchToLight": "切換到淺色模式", - "switchToDark": "切換到深色模式" + "toggle": "Toggle theme", + "switchToLight": "Switch to light mode", + "switchToDark": "Switch to dark mode" }, "version": { - "selectLabel": "選擇 API 版本" - }, - "language": { - "selectLabel": "選擇語言" + "selectLabel": "Select API version" }, "nav": { - "mainMenu": "主菜单", - "toggleMenu": "切换菜单", - "home": "首页", - "breadcrumb": "面包屑导航", - "mainNavigation": "主导航", - "selectVersion": "选择文档版本" + "mainMenu": "Main menu", + "toggleMenu": "Toggle menu", + "home": "home", + "breadcrumb": "Breadcrumb", + "mainNavigation": "Main navigation", + "selectVersion": "Select documentation version" }, "menu": { "main": { - "docs": "文档", + "docs": "Docs", "api": "API", - "resources": "资源", - "blog": "博客", - "support": "支持" + "resources": "Resources", + "blog": "Blog", + "support": "Support" }, "sections": { - "gettingStarted": "入门", - "guide": "指南", - "migration": "迁移指南", - "advanced": "高级主题", + "gettingStarted": "Getting started", + "guide": "Guide", + "migration": "Migration guides", + "advanced": "Advanced topics", "express": "express()", - "application": "应用程序", - "request": "请求", - "response": "响应", - "router": "路由器", - "middleware": "中间件" + "application": "Application", + "request": "Request", + "response": "Response", + "router": "Router", + "middleware": "Middleware" }, "items": { - "installing": "安装", + "installing": "Installing", "helloWorld": "Hello world", - "expressGenerator": "Express 生成器", - "basicRouting": "基础路由", - "staticFiles": "静态文件服务", - "examples": "示例", - "faq": "常见问题", - "routing": "路由", - "writingMiddleware": "编写中间件", - "usingMiddleware": "使用中间件", - "usingTemplateEngines": "使用模板引擎", - "errorHandling": "错误处理", - "debugging": "调试", - "behindProxies": "代理背后", - "databaseIntegration": "数据库集成", - "overridingExpressApi": "覆盖 Express API", - "migratingTo4": "迁移到 Express 4", - "migratingTo5": "迁移到 Express 5", - "buildingTemplateEngines": "构建模板引擎", - "bestPracticePerformance": "性能最佳实践", - "bestPracticeSecurity": "安全最佳实践", - "healthcheckGracefulShutdown": "健康检查 & 优雅关闭", - "securityUpdates": "安全更新", - "overview": "概览", - "properties": "属性", - "methods": "方法", - "events": "事件", - "types": "内置", - "community": "社区", - "glossary": "术语表", - "contributing": "贡献", - "utils": "工具", - "middleware": "中间件" + "expressGenerator": "Express generator", + "basicRouting": "Basic routing", + "staticFiles": "Serving static files", + "examples": "Examples", + "faq": "FAQ", + "routing": "Routing", + "writingMiddleware": "Writing middleware", + "usingMiddleware": "Using middleware", + "usingTemplateEngines": "Using template engines", + "errorHandling": "Error handling", + "debugging": "Debugging", + "behindProxies": "Behind proxies", + "databaseIntegration": "Database integration", + "overridingExpressApi": "Overriding the Express API", + "migratingTo4": "Moving to Express 4", + "migratingTo5": "Moving to Express 5", + "buildingTemplateEngines": "Building template engines", + "bestPracticePerformance": "Performance best practices", + "bestPracticeSecurity": "Security best practices", + "healthcheckGracefulShutdown": "Health checks & graceful shutdown", + "securityUpdates": "Security updates", + "overview": "Overview", + "properties": "Properties", + "methods": "Methods", + "events": "Events", + "types": "Built-in", + "community": "Community", + "glossary": "Glossary", + "contributing": "Contributing", + "utils": "Utilities", + "middleware": "Middleware" }, "aria": { - "docs": "文档", - "api": "API 参考", - "resources": "资源", - "blog": "博客", - "support": "支持", - "installing": "安装 Express", - "helloWorld": "Hello world 示例", - "expressGenerator": "Express 生成器", - "routing": "路由指南", - "writingMiddleware": "编写中间件指南", - "usingMiddleware": "使用中间件指南", - "usingTemplateEngines": "使用模板引擎指南", - "errorHandling": "错误处理指南", - "debugging": "调试 Express", - "behindProxies": "代理背后的 Express", - "databaseIntegration": "数据库集成指南", - "overridingExpressApi": "覆盖 Express API 指南", - "application": "应用程序概览", - "request": "请求概览", - "response": "响应概览", - "router": "路由器概览", - "middleware": "中间件资源", - "community": "社区资源", - "glossary": "术语表", - "contributing": "贡献指南", - "utils": "工具" + "docs": "Documentation", + "api": "API Reference", + "resources": "Resources", + "blog": "Blog", + "support": "Support", + "installing": "Installing Express", + "helloWorld": "Hello world example", + "expressGenerator": "Express generator", + "routing": "Routing guide", + "writingMiddleware": "Writing middleware guide", + "usingMiddleware": "Using middleware guide", + "usingTemplateEngines": "Using template engines guide", + "errorHandling": "Error handling guide", + "debugging": "Debugging Express", + "behindProxies": "Express behind proxies", + "databaseIntegration": "Database integration guide", + "overridingExpressApi": "Overriding the Express API guide", + "application": "Application overview", + "request": "Request overview", + "response": "Response overview", + "router": "Router overview", + "middleware": "Middleware resources", + "community": "Community resources", + "glossary": "Glossary of terms", + "contributing": "Contributing guide", + "utils": "Utilities" } }, "doc": { - "previousPage": "上一页", - "nextPage": "下一页", - "pageNavigation": "页面导航" + "previousPage": "Previous", + "nextPage": "Next", + "pageNavigation": "Page navigation" }, "page": { - "editOnGitHub": "在 GitHub 上编辑", - "translateThis": "翻译此页面" + "editOnGitHub": "Edit on GitHub", + "translateThis": "Translate this page" }, "post": { - "share": "分享", - "shareOnX": "在 X 上分享", - "shareOnBluesky": "在 Bluesky 上分享", - "shareOnLinkedIn": "在 LinkedIn 上分享", - "shareOnSlack": "在 Slack 上分享", - "shareOnTelegram": "在 Telegram 上分享", - "shareOnWhatsApp": "在 WhatsApp 上分享", - "rssFeed": "RSS 订阅", - "copyLink": "复制链接", - "linkCopied": "链接已复制！", - "toc": "本页内容", - "more": "更多 Express 内容", - "writeBanner": "有兴趣写文章吗？\n查看我们的指南开始。", - "writeGuidelines": "阅读指南" + "share": "Share", + "shareOnX": "Share on X", + "shareOnBluesky": "Share on Bluesky", + "shareOnLinkedIn": "Share on LinkedIn", + "shareOnSlack": "Share on Slack", + "shareOnTelegram": "Share on Telegram", + "shareOnWhatsApp": "Share on WhatsApp", + "rssFeed": "RSS Feed", + "copyLink": "Copy link", + "linkCopied": "Link copied!", + "toc": "On this page", + "more": "More from Express", + "writeBanner": "Interested in writing a post? \n Check out our guidelines to get started.", + "writeGuidelines": "Read the guidelines" }, "toc": { - "overview": "概览" + "overview": "Overview" }, "features": { - "title": "清晰胜于复杂。为每位开发者而设。", + "title": "Clarity over complexity. For every developer.", "performance": { - "title": "性能", - "body": "Express 提供了 Web 应用的基础功能层，同时不隐藏你熟悉的 Node.js 功能。" + "title": "Performance", + "body": "Express provides a thin layer of fundamental web application features, without obscuring Node.js features that you know and love." }, "api": { - "title": "API", - "body": "借助丰富的 HTTP 工具方法和中间件，可快速轻松地创建强大的 API。" + "title": "APIs", + "body": "With a myriad of HTTP utility methods and middleware at your disposal, creating a robust API is quick and easy." }, "middleware": { - "title": "中间件", - "body": "Express 是轻量且灵活的路由框架，核心功能最小，可通过中间件模块扩展。" + "title": "Middleware", + "body": "Express is a lightweight and flexible routing framework with minimal core features meant to be augmented through the use of Express middleware modules." }, "webapplication": { - "title": "Web 应用", - "body": "Express 是一个简洁灵活的 Node.js Web 应用框架，为 Web 和移动应用提供强大功能集。" + "title": "Web Applications", + "body": "Express is a minimal and flexible Node.js web application framework that provides a robust set of features for web and mobile applications." } }, "error404": { - "title": "404 - 页面未找到", - "description": "您访问的页面不存在。", - "heading": "页面未找到", - "message": "您访问的页面不存在或已被移动。", - "goHome": "返回首页" + "title": "404 - Page Not Found", + "description": "The page you are looking for could not be found.", + "heading": "Page Not Found", + "message": "The page you are looking for does not exist or has been moved.", + "goHome": "Go to Home" }, "hero": { - "tagline": "Node.js 的快速、简约 Web 框架", - "getStarted": "开始使用", - "videoPause": "暂停背景视频", - "videoPlay": "播放背景视频" + "tagline": "Fast, unopinionated, minimalist web framework for Node.js", + "getStarted": "Get Started", + "videoPause": "Pause background video", + "videoPlay": "Play background video" } } From a1b6e58a53e57c2d4af421fbd1c923bb0b5f850f Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Sat, 25 Apr 2026 16:21:51 +0000 Subject: [PATCH 2/5] remove fallbacks --- src/pages/[lang]/[...slug].astro | 121 ------------------------------- 1 file changed, 121 deletions(-) diff --git a/src/pages/[lang]/[...slug].astro b/src/pages/[lang]/[...slug].astro index eda57c401b..a1596e7731 100644 --- a/src/pages/[lang]/[...slug].astro +++ b/src/pages/[lang]/[...slug].astro @@ -12,7 +12,6 @@ import type { LanguageCode } from '@i18n/locales'; export async function getStaticPaths() { const DEFAULT_VERSION = '5x'; const VERSION_PREFIXES = ['5x', '4x', '3x']; - const DEFAULT_LANG = 'en'; const pages = await getCollection('docs'); const api = await getCollection('api'); @@ -25,18 +24,6 @@ export async function getStaticPaths() { props: { page: AnyPage; version?: string }; }> = []; - // Helper to create a map of existing content for fallback logic - const existingContent = new Map(); - pages.forEach((page) => { - const [lang, ...slugParts] = page.id.split('/'); - const fullSlug = slugParts.join('/'); - existingContent.set(`${lang}/${fullSlug}`, page); - }); - - api.forEach((page) => { - existingContent.set(`en/${page.id}`, page); - }); - pages.forEach((page) => { const [lang, ...slugParts] = page.id.split('/'); const fullSlug = slugParts.join('/'); @@ -59,39 +46,6 @@ export async function getStaticPaths() { }); }); - for (const lang of Object.keys(languages)) { - api.forEach((page) => { - const slugParts = page.id.split('/'); - const version = slugParts[0]; - const slug = page.id; - - paths.push({ - params: { lang, slug }, - props: { page, version }, - }); - }); - } - - const defaultVersionApiPages = api.filter((page) => page.id.startsWith(`${DEFAULT_VERSION}/`)); - - for (const lang of Object.keys(languages)) { - defaultVersionApiPages.forEach((page) => { - const [, ...restSlugParts] = page.id.split('/'); - const nonVersionedSlug = restSlugParts.join('/'); - - const exists = paths.some( - (p) => p.params.lang === lang && p.params.slug === nonVersionedSlug - ); - - if (!exists && nonVersionedSlug) { - paths.push({ - params: { lang, slug: nonVersionedSlug }, - props: { page, version: DEFAULT_VERSION }, - }); - } - }); - } - const defaultVersionPages = pages.filter((page) => { const [, ...slugParts] = page.id.split('/'); return slugParts[0] === DEFAULT_VERSION; @@ -111,81 +65,6 @@ export async function getStaticPaths() { } }); - // Fallback for non-versioned default-version slugs: use English content for missing languages - const englishDefaultVersionPages = defaultVersionPages.filter((p) => - p.id.startsWith(`${DEFAULT_LANG}/`) - ); - - for (const lang of Object.keys(languages)) { - if (lang === DEFAULT_LANG) continue; - - englishDefaultVersionPages.forEach((page) => { - const [, , ...restSlugParts] = page.id.split('/'); - const nonVersionedSlug = restSlugParts.join('/'); - - const exists = paths.some( - (p) => p.params.lang === lang && p.params.slug === nonVersionedSlug - ); - - if (!exists && nonVersionedSlug) { - paths.push({ - params: { lang, slug: nonVersionedSlug }, - props: { page, version: DEFAULT_VERSION }, - }); - } - }); - } - - // Fallback: Create paths for non-English languages using English pages content - for (const lang of Object.keys(languages)) { - if (lang === DEFAULT_LANG) continue; - - const englishContentPages = contentPages.filter((p) => p.id.startsWith(`${DEFAULT_LANG}/`)); - - englishContentPages.forEach((page) => { - const [, ...slugParts] = page.id.split('/'); - const fullSlug = slugParts.join('/'); - - const langSpecificExists = paths.some( - (p) => p.params.lang === lang && p.params.slug === fullSlug - ); - - if (!langSpecificExists) { - paths.push({ - params: { lang, slug: fullSlug }, - props: { page }, - }); - } - }); - } - - // Fallback: Create paths for non-English languages using English docs content - for (const lang of Object.keys(languages)) { - if (lang === DEFAULT_LANG) continue; // Skip English, already added - - const englishPages = pages.filter((p) => p.id.startsWith(`${DEFAULT_LANG}/`)); - - englishPages.forEach((page) => { - const [, ...slugParts] = page.id.split('/'); - const fullSlug = slugParts.join('/'); - - const langSpecificExists = paths.some( - (p) => p.params.lang === lang && p.params.slug === fullSlug - ); - - // If no language-specific version exists, add fallback to English - if (!langSpecificExists) { - paths.push({ - params: { lang, slug: fullSlug }, - props: { - page, - version: slugParts[0] === DEFAULT_VERSION ? DEFAULT_VERSION : slugParts[0], - }, - }); - } - }); - } - return paths; } From 3045ff080eeeeacde098544c3363d51d3236cf69 Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Sat, 25 Apr 2026 16:25:12 +0000 Subject: [PATCH 3/5] fix lint --- .../docs/de/4x/guide/behind-proxies.mdx | 14 +- .../docs/de/4x/guide/error-handling.mdx | 32 ++--- src/content/docs/de/4x/guide/routing.mdx | 36 ++--- .../docs/de/4x/guide/using-middleware.mdx | 38 ++--- .../de/4x/guide/using-template-engines.mdx | 6 +- .../docs/de/4x/guide/writing-middleware.mdx | 14 +- .../docs/de/4x/starter/basic-routing.mdx | 10 +- src/content/docs/de/4x/starter/examples.mdx | 58 ++++---- src/content/docs/de/4x/starter/generator.mdx | 2 +- .../docs/de/4x/starter/hello-world.mdx | 6 +- .../docs/de/5x/guide/behind-proxies.mdx | 14 +- .../docs/de/5x/guide/error-handling.mdx | 32 ++--- src/content/docs/de/5x/guide/routing.mdx | 36 ++--- .../docs/de/5x/guide/using-middleware.mdx | 38 ++--- .../de/5x/guide/using-template-engines.mdx | 6 +- .../docs/de/5x/guide/writing-middleware.mdx | 14 +- .../docs/de/5x/starter/basic-routing.mdx | 10 +- src/content/docs/de/5x/starter/examples.mdx | 54 +++---- src/content/docs/de/5x/starter/generator.mdx | 2 +- .../docs/de/5x/starter/hello-world.mdx | 6 +- .../docs/es/4x/guide/behind-proxies.mdx | 18 +-- .../docs/es/4x/guide/error-handling.mdx | 42 +++--- src/content/docs/es/4x/guide/routing.mdx | 58 ++++---- .../docs/es/4x/guide/using-middleware.mdx | 44 +++--- .../es/4x/guide/using-template-engines.mdx | 6 +- .../docs/es/4x/guide/writing-middleware.mdx | 28 ++-- .../docs/es/4x/starter/basic-routing.mdx | 10 +- src/content/docs/es/4x/starter/examples.mdx | 58 ++++---- src/content/docs/es/4x/starter/generator.mdx | 2 +- .../docs/es/4x/starter/hello-world.mdx | 6 +- .../docs/es/5x/guide/behind-proxies.mdx | 18 +-- .../docs/es/5x/guide/error-handling.mdx | 42 +++--- src/content/docs/es/5x/guide/routing.mdx | 58 ++++---- .../docs/es/5x/guide/using-middleware.mdx | 44 +++--- .../es/5x/guide/using-template-engines.mdx | 6 +- .../docs/es/5x/guide/writing-middleware.mdx | 24 ++-- .../docs/es/5x/starter/basic-routing.mdx | 10 +- src/content/docs/es/5x/starter/examples.mdx | 54 +++---- src/content/docs/es/5x/starter/generator.mdx | 2 +- .../docs/es/5x/starter/hello-world.mdx | 6 +- .../docs/fr/4x/guide/behind-proxies.mdx | 20 +-- .../docs/fr/4x/guide/error-handling.mdx | 30 ++-- src/content/docs/fr/4x/guide/routing.mdx | 30 ++-- .../docs/fr/4x/guide/using-middleware.mdx | 34 ++--- .../fr/4x/guide/using-template-engines.mdx | 6 +- .../docs/fr/4x/guide/writing-middleware.mdx | 22 +-- .../docs/fr/4x/starter/basic-routing.mdx | 10 +- src/content/docs/fr/4x/starter/examples.mdx | 60 ++++---- src/content/docs/fr/4x/starter/generator.mdx | 2 +- .../docs/fr/4x/starter/hello-world.mdx | 6 +- .../docs/fr/5x/guide/behind-proxies.mdx | 20 +-- .../docs/fr/5x/guide/error-handling.mdx | 30 ++-- src/content/docs/fr/5x/guide/routing.mdx | 30 ++-- .../docs/fr/5x/guide/using-middleware.mdx | 34 ++--- .../fr/5x/guide/using-template-engines.mdx | 6 +- .../docs/fr/5x/guide/writing-middleware.mdx | 18 +-- .../docs/fr/5x/starter/basic-routing.mdx | 10 +- src/content/docs/fr/5x/starter/examples.mdx | 54 +++---- src/content/docs/fr/5x/starter/generator.mdx | 2 +- .../docs/fr/5x/starter/hello-world.mdx | 6 +- .../docs/it/4x/guide/behind-proxies.mdx | 20 +-- .../docs/it/4x/guide/error-handling.mdx | 38 ++--- src/content/docs/it/4x/guide/routing.mdx | 44 +++--- .../docs/it/4x/guide/using-middleware.mdx | 38 ++--- .../it/4x/guide/using-template-engines.mdx | 6 +- .../docs/it/4x/guide/writing-middleware.mdx | 28 ++-- .../docs/it/4x/starter/basic-routing.mdx | 10 +- src/content/docs/it/4x/starter/examples.mdx | 60 ++++---- src/content/docs/it/4x/starter/generator.mdx | 2 +- .../docs/it/4x/starter/hello-world.mdx | 6 +- .../docs/it/5x/guide/behind-proxies.mdx | 20 +-- .../docs/it/5x/guide/error-handling.mdx | 38 ++--- src/content/docs/it/5x/guide/routing.mdx | 44 +++--- .../docs/it/5x/guide/using-middleware.mdx | 38 ++--- .../it/5x/guide/using-template-engines.mdx | 6 +- .../docs/it/5x/guide/writing-middleware.mdx | 24 ++-- .../docs/it/5x/starter/basic-routing.mdx | 10 +- src/content/docs/it/5x/starter/examples.mdx | 54 +++---- src/content/docs/it/5x/starter/generator.mdx | 2 +- .../docs/it/5x/starter/hello-world.mdx | 6 +- .../docs/ja/4x/guide/behind-proxies.mdx | 18 +-- src/content/docs/ja/4x/guide/debugging.mdx | 12 +- .../docs/ja/4x/guide/error-handling.mdx | 10 +- src/content/docs/ja/4x/guide/routing.mdx | 28 ++-- .../docs/ja/4x/guide/using-middleware.mdx | 28 ++-- .../ja/4x/guide/using-template-engines.mdx | 6 +- .../docs/ja/4x/guide/writing-middleware.mdx | 10 +- .../docs/ja/4x/starter/basic-routing.mdx | 10 +- src/content/docs/ja/4x/starter/examples.mdx | 58 ++++---- src/content/docs/ja/4x/starter/generator.mdx | 2 +- .../docs/ja/4x/starter/hello-world.mdx | 4 +- .../docs/ja/5x/guide/behind-proxies.mdx | 18 +-- src/content/docs/ja/5x/guide/debugging.mdx | 12 +- .../docs/ja/5x/guide/error-handling.mdx | 10 +- src/content/docs/ja/5x/guide/routing.mdx | 28 ++-- .../docs/ja/5x/guide/using-middleware.mdx | 28 ++-- .../ja/5x/guide/using-template-engines.mdx | 6 +- .../docs/ja/5x/guide/writing-middleware.mdx | 10 +- .../docs/ja/5x/starter/basic-routing.mdx | 10 +- src/content/docs/ja/5x/starter/examples.mdx | 54 +++---- src/content/docs/ja/5x/starter/generator.mdx | 2 +- .../docs/ja/5x/starter/hello-world.mdx | 4 +- .../docs/ko/4x/guide/behind-proxies.mdx | 6 +- .../docs/ko/4x/guide/error-handling.mdx | 12 +- src/content/docs/ko/4x/guide/routing.mdx | 8 +- .../docs/ko/4x/guide/using-middleware.mdx | 28 ++-- .../ko/4x/guide/using-template-engines.mdx | 6 +- .../docs/ko/4x/guide/writing-middleware.mdx | 10 +- .../docs/ko/4x/starter/basic-routing.mdx | 10 +- src/content/docs/ko/4x/starter/examples.mdx | 54 +++---- src/content/docs/ko/4x/starter/generator.mdx | 2 +- .../docs/ko/4x/starter/hello-world.mdx | 4 +- .../docs/ko/5x/guide/behind-proxies.mdx | 6 +- .../docs/ko/5x/guide/error-handling.mdx | 12 +- src/content/docs/ko/5x/guide/routing.mdx | 8 +- .../docs/ko/5x/guide/using-middleware.mdx | 28 ++-- .../ko/5x/guide/using-template-engines.mdx | 6 +- .../docs/ko/5x/guide/writing-middleware.mdx | 10 +- .../docs/ko/5x/starter/basic-routing.mdx | 10 +- src/content/docs/ko/5x/starter/examples.mdx | 54 +++---- src/content/docs/ko/5x/starter/generator.mdx | 2 +- .../docs/ko/5x/starter/hello-world.mdx | 4 +- .../docs/pt-br/4x/guide/behind-proxies.mdx | 15 +- .../docs/pt-br/4x/guide/error-handling.mdx | 26 ++-- src/content/docs/pt-br/4x/guide/routing.mdx | 40 +++--- .../docs/pt-br/4x/guide/using-middleware.mdx | 40 +++--- .../pt-br/4x/guide/using-template-engines.mdx | 6 +- .../pt-br/4x/guide/writing-middleware.mdx | 22 +-- .../docs/pt-br/4x/starter/basic-routing.mdx | 10 +- .../docs/pt-br/4x/starter/examples.mdx | 58 ++++---- .../docs/pt-br/4x/starter/generator.mdx | 6 +- .../docs/pt-br/4x/starter/hello-world.mdx | 6 +- .../docs/pt-br/5x/guide/behind-proxies.mdx | 15 +- .../docs/pt-br/5x/guide/error-handling.mdx | 26 ++-- src/content/docs/pt-br/5x/guide/routing.mdx | 40 +++--- .../docs/pt-br/5x/guide/using-middleware.mdx | 40 +++--- .../pt-br/5x/guide/using-template-engines.mdx | 6 +- .../pt-br/5x/guide/writing-middleware.mdx | 18 +-- .../docs/pt-br/5x/starter/basic-routing.mdx | 10 +- .../docs/pt-br/5x/starter/examples.mdx | 54 +++---- .../docs/pt-br/5x/starter/generator.mdx | 6 +- .../docs/pt-br/5x/starter/hello-world.mdx | 6 +- .../docs/zh-tw/4x/guide/behind-proxies.mdx | 6 +- .../docs/zh-tw/4x/guide/error-handling.mdx | 12 +- src/content/docs/zh-tw/4x/guide/routing.mdx | 8 +- .../docs/zh-tw/4x/guide/using-middleware.mdx | 28 ++-- .../zh-tw/4x/guide/using-template-engines.mdx | 6 +- .../zh-tw/4x/guide/writing-middleware.mdx | 10 +- .../docs/zh-tw/4x/starter/basic-routing.mdx | 10 +- .../docs/zh-tw/4x/starter/examples.mdx | 54 +++---- .../docs/zh-tw/4x/starter/generator.mdx | 2 +- .../docs/zh-tw/4x/starter/hello-world.mdx | 4 +- .../docs/zh-tw/5x/guide/behind-proxies.mdx | 6 +- .../docs/zh-tw/5x/guide/error-handling.mdx | 12 +- src/content/docs/zh-tw/5x/guide/routing.mdx | 8 +- .../docs/zh-tw/5x/guide/using-middleware.mdx | 28 ++-- .../zh-tw/5x/guide/using-template-engines.mdx | 6 +- .../zh-tw/5x/guide/writing-middleware.mdx | 10 +- .../docs/zh-tw/5x/starter/basic-routing.mdx | 10 +- .../docs/zh-tw/5x/starter/examples.mdx | 54 +++---- .../docs/zh-tw/5x/starter/generator.mdx | 2 +- .../docs/zh-tw/5x/starter/hello-world.mdx | 4 +- .../de/advanced/best-practice-security.mdx | 96 ++++++------- .../pages/de/advanced/security-updates.mdx | 98 ++++++------- .../pages/de/guide/database-integration.mdx | 90 ++++++------ src/content/pages/de/guide/migrating-4.mdx | 57 ++++---- src/content/pages/de/guide/migrating-5.mdx | 68 ++++----- src/content/pages/de/resources/glossary.mdx | 6 +- src/content/pages/de/resources/utils.md | 18 +-- src/content/pages/de/support.md | 16 +-- .../es/advanced/best-practice-security.mdx | 98 ++++++------- .../pages/es/advanced/security-updates.mdx | 98 ++++++------- .../pages/es/guide/database-integration.mdx | 135 +++++++++--------- src/content/pages/es/guide/migrating-4.mdx | 62 ++++---- src/content/pages/es/guide/migrating-5.mdx | 68 ++++----- src/content/pages/es/resources/glossary.mdx | 6 +- src/content/pages/es/resources/utils.md | 18 +-- src/content/pages/es/support.md | 16 +-- .../fr/advanced/best-practice-performance.md | 2 +- .../fr/advanced/best-practice-security.mdx | 90 ++++++------ .../pages/fr/advanced/security-updates.mdx | 98 ++++++------- .../pages/fr/guide/database-integration.mdx | 79 +++++----- src/content/pages/fr/guide/migrating-4.mdx | 51 ++++--- src/content/pages/fr/guide/migrating-5.mdx | 56 ++++---- src/content/pages/fr/resources/glossary.mdx | 6 +- src/content/pages/fr/resources/utils.md | 18 +-- src/content/pages/fr/support.md | 16 +-- .../it/advanced/best-practice-security.mdx | 98 ++++++------- .../pages/it/advanced/security-updates.mdx | 98 ++++++------- .../pages/it/guide/database-integration.mdx | 100 ++++++------- src/content/pages/it/guide/migrating-4.mdx | 43 +++--- src/content/pages/it/guide/migrating-5.mdx | 58 ++++---- src/content/pages/it/resources/glossary.mdx | 6 +- src/content/pages/it/resources/utils.md | 18 +-- src/content/pages/it/support.md | 16 +-- .../ja/advanced/best-practice-performance.md | 8 +- .../ja/advanced/best-practice-security.mdx | 86 +++++------ .../pages/ja/advanced/security-updates.mdx | 98 ++++++------- .../pages/ja/guide/database-integration.mdx | 30 ++-- src/content/pages/ja/guide/migrating-4.mdx | 25 ++-- src/content/pages/ja/guide/migrating-5.mdx | 34 ++--- src/content/pages/ja/resources/glossary.mdx | 6 +- src/content/pages/ja/resources/utils.md | 20 +-- src/content/pages/ja/support.md | 16 +-- .../ko/advanced/best-practice-security.mdx | 88 ++++++------ .../pages/ko/advanced/security-updates.mdx | 98 ++++++------- .../pages/ko/guide/database-integration.mdx | 30 ++-- src/content/pages/ko/guide/migrating-4.mdx | 16 +-- src/content/pages/ko/guide/migrating-5.mdx | 34 ++--- src/content/pages/ko/resources/glossary.mdx | 6 +- src/content/pages/ko/resources/utils.md | 18 +-- src/content/pages/ko/support.md | 16 +-- .../pt-br/advanced/best-practice-security.mdx | 88 ++++++------ .../pages/pt-br/advanced/security-updates.mdx | 98 ++++++------- .../pt-br/guide/database-integration.mdx | 90 ++++++------ src/content/pages/pt-br/guide/migrating-4.mdx | 30 ++-- src/content/pages/pt-br/guide/migrating-5.mdx | 62 ++++---- .../pages/pt-br/resources/glossary.mdx | 6 +- src/content/pages/pt-br/resources/utils.md | 18 +-- src/content/pages/pt-br/support.md | 16 +-- .../zh-tw/advanced/best-practice-security.mdx | 88 ++++++------ .../pages/zh-tw/advanced/security-updates.mdx | 98 ++++++------- .../zh-tw/guide/database-integration.mdx | 30 ++-- src/content/pages/zh-tw/guide/migrating-4.mdx | 16 +-- src/content/pages/zh-tw/guide/migrating-5.mdx | 34 ++--- .../pages/zh-tw/resources/glossary.mdx | 6 +- src/content/pages/zh-tw/resources/utils.md | 18 +-- src/content/pages/zh-tw/support.md | 16 +-- 228 files changed, 3226 insertions(+), 3186 deletions(-) diff --git a/src/content/docs/de/4x/guide/behind-proxies.mdx b/src/content/docs/de/4x/guide/behind-proxies.mdx index 786e7aff5f..42b2f725fb 100644 --- a/src/content/docs/de/4x/guide/behind-proxies.mdx +++ b/src/content/docs/de/4x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ Wenn Sie auf `true` setzen, ist es wichtig sicherzustellen, dass der letzte Reve Eine IP-Adresse, ein Subnetz oder ein Array von IP-Adressen und Subnetzen, die darauf vertrauen, dass es sich um einen Reverse Proxy handelt. Die folgende Liste zeigt die vorkonfigurierten Subnetznamen an: -* loopback - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` Sie können IP-Adressen auf jede der folgenden Arten festlegen: @@ -90,12 +90,14 @@ Das Aktivieren von `trust proxy` hat folgende Auswirkungen: `X-Forwarded-Host` Header gesetzt wurde , die vom Client oder vom Proxy gesetzt werden kann.
  • - `X-Forwarded-Proto` kann vom Reverse Proxy gesetzt werden, um der App mitzuteilen, ob es `https` oder - `http` oder sogar ein ungültiger Name ist. Dieser Wert wird von [req.protocol]reflektiert (/en/api#req.protocol). + `X-Forwarded-Proto` kann vom Reverse Proxy gesetzt werden, um der App mitzuteilen, ob es `https` + oder `http` oder sogar ein ungültiger Name ist. Dieser Wert wird von [req.protocol]reflektiert + (/en/api#req.protocol).
  • Die Werte [req.ip](/en/api#req.ip) und [req.ips](/en/api#req.ips) werden auf der Basis der - Socket-Adresse und des `X-Forwarded-For` Headers gefüllt beginnend an der ersten nicht vertrauenswürdigen Adresse. + Socket-Adresse und des `X-Forwarded-For` Headers gefüllt beginnend an der ersten nicht + vertrauenswürdigen Adresse.
    • diff --git a/src/content/docs/de/4x/guide/error-handling.mdx b/src/content/docs/de/4x/guide/error-handling.mdx index d3d51364b4..9db119db26 100644 --- a/src/content/docs/de/4x/guide/error-handling.mdx +++ b/src/content/docs/de/4x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Verstehen Sie, wie Express.js Fehler im synchronen und asynchronen import Alert from '@components/primitives/Alert/Alert.astro'; -*Error Handling* bezieht sich darauf, wie Express Fehler fängt und verarbeitet, die +_Error Handling_ bezieht sich darauf, wie Express Fehler fängt und verarbeitet, die sowohl synchron als auch asynchron auftritt. Express kommt mit einem Standardfehler \-Handler, damit Sie nicht Ihren eigenen schreiben müssen, um loszulegen. @@ -30,11 +30,11 @@ catch and process them. Zum Beispiel: ```js app.get('/', (req, res, next) => { - fs. eadFile('/file-does-not-exist', (err, data) => { + fs.eadFile('/file-does-not-exist', (err, data) => { if (err) { next(err); // Fehler an Express übergeben. } else { - res. end(data); + res.end(data); } }); }); @@ -161,12 +161,12 @@ Setze die Umgebungsvariable `NODE_ENV` auf `production`, um die App im Produktio Wenn ein Fehler geschrieben wird, werden folgende Informationen zur Antwort hinzugefügt: -* Der `res.statusCode` wurde von `err.status` (oder `err.statusCode`) gesetzt. Wenn +- Der `res.statusCode` wurde von `err.status` (oder `err.statusCode`) gesetzt. Wenn sich dieser Wert außerhalb des 4xx oder 5xx Bereichs befindet, wird er auf 500 gesetzt. -* Die `res.statusMessage` wurde gemäß dem Statuscode gesetzt. -* Der Körper wird der HTML-Code der Statuscode-Nachricht sein, wenn in der Produktion +- Die `res.statusMessage` wurde gemäß dem Statuscode gesetzt. +- Der Körper wird der HTML-Code der Statuscode-Nachricht sein, wenn in der Produktion \-Umgebung, andernfalls 'err.stack' ist. -* Alle in einem `err.headers` Objekt angegebenen Header. +- Alle in einem `err.headers` Objekt angegebenen Header. Wenn du `next()` mit einem Fehler aufruft, nachdem du die Antwort geschrieben hast (z. B. wenn beim Streamen der @@ -212,12 +212,12 @@ const bodyParser = require('body-parser'); const methodOverride = require('method-override'); app.use( - bodyParser. rlencoded({ + bodyParser.rlencoded({ extended: true, }) ); app.use(bodyParser.json()); -app. se(methodOverride()); +app.se(methodOverride()); app.use((err, req, res, next) => { // Logik }); @@ -234,12 +234,12 @@ für Anfragen mit `XHR` und denen ohne folgende zu definieren: const bodyParser = require('body-parser'); const methodOverride = require('method-override'); -app. se( +app.se( bodyParser.urlencoded({ extended: true, }) ); -app. se(bodyParser.json()); +app.se(bodyParser.json()); app.use(methodOverride()); app.use(logErrors); app.use(clientErrorHandler); @@ -258,12 +258,12 @@ function logErrors(err, req, res, next) { Auch in diesem Beispiel wird `clientErrorHandler` wie folgt definiert; in diesem Fall wird der Fehler explizit an den nächsten weitergegeben. -Beachten Sie, dass, wenn *not* in einer Fehlerbehandlungsfunktion "Weiter" aufruft, Sie dafür verantwortlich sind, die Antwort zu schreiben (und zu beenden). Andernfalls werden diese Anträge "hängen" und sind nicht für die Müllsammlung berechtigt. +Beachten Sie, dass, wenn _not_ in einer Fehlerbehandlungsfunktion "Weiter" aufruft, Sie dafür verantwortlich sind, die Antwort zu schreiben (und zu beenden). Andernfalls werden diese Anträge "hängen" und sind nicht für die Müllsammlung berechtigt. ```js function clientErrorHandler(err, req, res, next) { if (req.xhr) { - res.status(500). end({ error: 'Something failed!' }); + res.status(500).end({ error: 'Something failed!' }); } else { next(err); } @@ -285,7 +285,7 @@ Wenn du einen Route-Handler mit mehreren Callback-Funktionen hast, kannst du den app.get( '/a_route_behind_paywall', (req, res, next) => { - if (!req.user. asPaid) { + if (!req.user.asPaid) { // weitere Bearbeitung dieser Anfrage next('route'); } else { @@ -293,9 +293,9 @@ app.get( } }, (req, res, next) => { - PaidContent. ind((err, doc) => { + PaidContent.ind((err, doc) => { if (err) return next(err); - res. son(doc); + res.son(doc); }); } ); diff --git a/src/content/docs/de/4x/guide/routing.mdx b/src/content/docs/de/4x/guide/routing.mdx index 709b3db818..58254d8832 100644 --- a/src/content/docs/de/4x/guide/routing.mdx +++ b/src/content/docs/de/4x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Lernen Sie, wie Sie Routen in Express.js Anwendungen definieren und import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* bezieht sich darauf, wie die Endpunkte einer Anwendung (URIs) auf Kundenanfragen reagieren. +_Routing_ bezieht sich darauf, wie die Endpunkte einer Anwendung (URIs) auf Kundenanfragen reagieren. Für eine Einführung in das Routing siehe [Basic routing](/en/starter/basic-routing). Du definierst Routing, indem du Methoden des Express `app` Objekts verwendest, die den HTTP-Methoden entsprechen; @@ -40,11 +40,11 @@ Der folgende Code ist ein Beispiel für Routen, die für die `GET` und die `POST ```js // GET Methode Route app.get('/', (req, res) => { - res. end('GET request to the homepage'); + res.end('GET request to the homepage'); }); // POST method route -app. ost('/', (req, res) => { +app.ost('/', (req, res) => { res.send('POST request to the homepage'); }); ``` @@ -52,7 +52,7 @@ app. ost('/', (req, res) => { Express unterstützt Methoden, die allen HTTP-Anfragemethoden entsprechen: `get`, `post` und so weiter. Für eine vollständige Liste siehe [app.METHOD](/en/5x/api#app.METHOD). -Es gibt eine spezielle Routing-Methode, `app.all()`, die benutzt wird, um Middleware-Funktionen an einem Pfad für *all* HTTP-Requestmethoden zu laden. Zum Beispiel wird der folgende Handler für Anfragen an die Route `"/secret"` ausgeführt, ob `GET` verwendet wird, `POST`, `PUT`, `DELETE`, oder jede andere HTTP-Anfragemethode, die im [http module]unterstützt wird (https://nodejs.org/api/http.html#http_http_methods). +Es gibt eine spezielle Routing-Methode, `app.all()`, die benutzt wird, um Middleware-Funktionen an einem Pfad für _all_ HTTP-Requestmethoden zu laden. Zum Beispiel wird der folgende Handler für Anfragen an die Route `"/secret"` ausgeführt, ob `GET` verwendet wird, `POST`, `PUT`, `DELETE`, oder jede andere HTTP-Anfragemethode, die im [http module]unterstützt wird (https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -244,10 +244,10 @@ Du kannst mehrere Callback-Funktionen bereitstellen, die sich wie [middleware](/ ```js app.get('/user/:id', (req, res, next) => { - if (req.params. d === '0') { + if (req.params.d === '0') { return next('route'); } - res. end(`User ${req.params.id}`); + res.end(`User ${req.params.id}`); }); app.get('/user/:id', (req, res) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { In diesem Beispiel: -* `GET /user/5` → behandelt durch die erste Route → sendet "Benutzer 5" -* `GET /user/0` → erste Routenaufrufe `next('route')`, überspringt zur nächsten passenden `/user/:id` Route +- `GET /user/5` → behandelt durch die erste Route → sendet "Benutzer 5" +- `GET /user/0` → erste Routenaufrufe `next('route')`, überspringt zur nächsten passenden `/user/:id` Route Routenhandler können in Form einer Funktion, eines Arrays von Funktionen oder Kombinationen beider sein, wie in den folgenden Beispielen gezeigt. @@ -276,11 +276,11 @@ Mehr als eine Callback-Funktion kann eine Route handhaben (stelle sicher, dass d app.get( '/example/b', (req, res, next) => { - Konsole. og('die Antwort wird von der nächsten Funktion gesendet. .'); + Konsole.og('die Antwort wird von der nächsten Funktion gesendet. .'); next(); }, (req, res) => { - res. end('Hallo von B!'); + res.end('Hallo von B!'); } ); ``` @@ -289,17 +289,17 @@ Ein Array von Callback-Funktionen kann eine Route handhaben. Zum Beispiel: ```js const cb0 = function (req, res, next) { - Konsole. og('CB0'); + Konsole.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; const cb2 = function (req, res) { - res. end('Hallo von C!'); + res.end('Hallo von C!'); }; app.get('/example/c', [cb0, cb1, cb2]); @@ -309,24 +309,24 @@ Eine Kombination aus unabhängigen Funktionen und Arrays von Funktionen kann ein ```js const cb0 = function (req, res, next) { - Konsole. og('CB0'); + Konsole.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; -App. et( +App.et( '/example/d', [cb0, cb1], (req, res, next) => { - Konsole. og('die Antwort wird von der nächsten Funktion gesendet. .'); + Konsole.og('die Antwort wird von der nächsten Funktion gesendet. .'); next(); }, (req, res) => { - res. end('Hallo von D!'); + res.end('Hallo von D!'); } ); ``` diff --git a/src/content/docs/de/4x/guide/using-middleware.mdx b/src/content/docs/de/4x/guide/using-middleware.mdx index 667105556e..adfe7537b4 100644 --- a/src/content/docs/de/4x/guide/using-middleware.mdx +++ b/src/content/docs/de/4x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express ist ein Routing- und Middleware-Webframework mit minimaler Funktionalität: Eine Express-Anwendung ist im Wesentlichen eine Reihe von Middleware-Funktionsaufrufen. -*Middleware* Funktionen sind Funktionen, die Zugriff auf das [request object](/en/5x/api#req) (`req`), das [Antwort-Objekt](/en/5x/api#res) (`res`) und die nächste Middleware-Funktion im Request-Antwort-Zyklus der Anwendung. Die nächste Middleware-Funktion wird üblicherweise durch eine Variable namens `next` bezeichnet. +_Middleware_ Funktionen sind Funktionen, die Zugriff auf das [request object](/en/5x/api#req) (`req`), das [Antwort-Objekt](/en/5x/api#res) (`res`) und die nächste Middleware-Funktion im Request-Antwort-Zyklus der Anwendung. Die nächste Middleware-Funktion wird üblicherweise durch eine Variable namens `next` bezeichnet. Middleware-Funktionen können folgende Aufgaben ausführen: -* Führe jeden Code aus. -* Änderungen an der Anfrage und den Antwort-Objekten vornehmen. -* Beende den Request-Antwort-Zyklus. -* Rufen Sie die nächste Middleware-Funktion im Stack auf. +- Führe jeden Code aus. +- Änderungen an der Anfrage und den Antwort-Objekten vornehmen. +- Beende den Request-Antwort-Zyklus. +- Rufen Sie die nächste Middleware-Funktion im Stack auf. Wenn die aktuelle Middleware-Funktion den Request-Antwort-Zyklus nicht beendet, muss sie `next()` aufrufen, um die Kontrolle an die nächste Middleware-Funktion zu übergeben. Andernfalls bleibt die Anfrage hängen. Eine Express-Anwendung kann folgende Arten von Middleware verwenden: -* [Middleware](#middleware.application) -* [Router-Level-Middleware](#middleware.router) -* [Error-handling middleware](#middleware.error-handling) -* [Integrierte Middleware](#middleware.built-in) -* [Middleware von Drittanbietern](#middleware.third-party) +- [Middleware](#middleware.application) +- [Router-Level-Middleware](#middleware.router) +- [Error-handling middleware](#middleware.error-handling) +- [Integrierte Middleware](#middleware.built-in) +- [Middleware von Drittanbietern](#middleware.third-party) Sie können Middleware auf Anwendungsebene und Routerebene mit einem optionalen Mount-Pfad laden. Sie können auch eine Reihe von Middleware-Funktionen zusammen laden, die einen Sub-Stack des Middleware-Systems an einem Mount-Punkt erzeugen. @@ -70,11 +70,11 @@ Es illustriert einen Middleware-Unterstapel, der Anfrageinformationen für jede app.use( '/user/:id', (req, res, next) => { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); }, (req, res, next) => { - console. og('Request Type:', req.method); + console.og('Request Type:', req.method); next(); } ); @@ -140,17 +140,17 @@ Dieses Beispiel zeigt ein Array mit einem Middleware-Sub-Stack an, das GET-Anfra ```js function logOriginalUrl(req, res, next) { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); } function logMethod(req, res, next) { - console.log('Request Type:', req. ethod); + console.log('Request Type:', req.ethod); next(); } const logStuff = [logOriginalUrl, logMethod]; -App. et('/user/:id', logStuff, (req, res, next) => { +App.et('/user/:id', logStuff, (req, res, next) => { res.send('User Info'); }); ``` @@ -246,7 +246,7 @@ App fällt. se('/admin', router, (req, res) => { -Bei der Fehlerbehebung der Middleware werden immer *vier* Argumente verwendet. Sie müssen vier Argumente angeben, um +Bei der Fehlerbehebung der Middleware werden immer _vier_ Argumente verwendet. Sie müssen vier Argumente angeben, um als Middleware-Funktion zu identifizieren. Selbst wenn du das `next` Objekt nicht verwenden musst, musst du es angeben, um die Signatur zu pflegen. Andernfalls wird das `next` Objekt als reguläre Middleware interpretiert und wird Fehler nicht bearbeiten. @@ -271,9 +271,9 @@ Ab Version 4.x ist Express nicht mehr abhängig von [Connect](https://github.com Express hat die folgenden integrierten Middleware-Funktionen: -* [express.static](/en/5x/api#express.static) dient statischen Assets wie HTML-Dateien, Bilder und so weiter. -* [express.json](/en/5x/api#express.json) analysiert eingehende Anfragen mit JSON Payloads. **HINWEIS: Verfügbar mit Express 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) analysiert eingehende Anfragen mit URL-kodierten Payloads. **HINWEIS: Verfügbar mit Express 4.16.0+** +- [express.static](/en/5x/api#express.static) dient statischen Assets wie HTML-Dateien, Bilder und so weiter. +- [express.json](/en/5x/api#express.json) analysiert eingehende Anfragen mit JSON Payloads. **HINWEIS: Verfügbar mit Express 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) analysiert eingehende Anfragen mit URL-kodierten Payloads. **HINWEIS: Verfügbar mit Express 4.16.0+** ## Drittanbieter-Middleware diff --git a/src/content/docs/de/4x/guide/using-template-engines.mdx b/src/content/docs/de/4x/guide/using-template-engines.mdx index 8fddcf43be..0a5b37a7c5 100644 --- a/src/content/docs/de/4x/guide/using-template-engines.mdx +++ b/src/content/docs/de/4x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Entdecken Sie, wie Sie Template-Engines wie Pug, Handlebars und EJS import Alert from '@components/primitives/Alert/Alert.astro'; -Eine *template engine* ermöglicht es Ihnen, statische Template-Dateien in Ihrer Anwendung zu verwenden. Zur Laufzeit ersetzt die Template-Engine +Eine _template engine_ ermöglicht es Ihnen, statische Template-Dateien in Ihrer Anwendung zu verwenden. Zur Laufzeit ersetzt die Template-Engine Variablen in einer Template-Datei mit aktuellen Werten und verwandelt die Vorlage in eine HTML-Datei, die an den Client gesendet wird. Dieser Ansatz erleichtert die Gestaltung einer HTML-Seite. @@ -13,9 +13,9 @@ Der [Express-Anwendungsgenerator](/en/starter/generator) verwendet [Pug](https:/ Um Template-Dateien zu rendern, setzen Sie folgende [Anwendungs-Einstellungen-Eigenschaften](/en/4x/api#app.set), in der Standardeinstellung `app.js`, die vom Generator erstellt wurde: -* `views`, das Verzeichnis, in dem sich die Template-Dateien befinden. Eg: `app.set('views', './views')`. +- `views`, das Verzeichnis, in dem sich die Template-Dateien befinden. Eg: `app.set('views', './views')`. Dies ist standardmäßig im Verzeichnis `views` im Root-Verzeichnis der Anwendung. -* `view engine`, die zu verwendende Template-Engine. Um zum Beispiel die Mückenvorlagen-Engine zu verwenden: `app.set('view engine', 'pug')`. +- `view engine`, die zu verwendende Template-Engine. Um zum Beispiel die Mückenvorlagen-Engine zu verwenden: `app.set('view engine', 'pug')`. Installieren Sie dann das entsprechende Template Engine npm Paket; zum Beispiel um Pug: diff --git a/src/content/docs/de/4x/guide/writing-middleware.mdx b/src/content/docs/de/4x/guide/writing-middleware.mdx index dd0cf8e493..f14875ff22 100644 --- a/src/content/docs/de/4x/guide/writing-middleware.mdx +++ b/src/content/docs/de/4x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Erfahren Sie, wie Sie benutzerdefinierte Middleware-Funktionen für import Alert from '@components/primitives/Alert/Alert.astro'; -*Middleware* Funktionen sind Funktionen, die Zugriff auf das [request object](/en/5x/api#req) (`req`), die [Antwort-Objekt](/en/5x/api#res) (`res`) und die `next` Funktion im Request-Antwort-Zyklus der Anwendung. Die `next`-Funktion ist eine Funktion im Express-Router, der beim Aufruf die Middleware ausführt, die die aktuelle Middleware abfolgt. +_Middleware_ Funktionen sind Funktionen, die Zugriff auf das [request object](/en/5x/api#req) (`req`), die [Antwort-Objekt](/en/5x/api#res) (`res`) und die `next` Funktion im Request-Antwort-Zyklus der Anwendung. Die `next`-Funktion ist eine Funktion im Express-Router, der beim Aufruf die Middleware ausführt, die die aktuelle Middleware abfolgt. Middleware-Funktionen können folgende Aufgaben ausführen: -* Führe jeden Code aus. -* Änderungen an der Anfrage und den Antwort-Objekten vornehmen. -* Beende den Request-Antwort-Zyklus. -* Rufen Sie die nächste Middleware im Stapel auf. +- Führe jeden Code aus. +- Änderungen an der Anfrage und den Antwort-Objekten vornehmen. +- Beende den Request-Antwort-Zyklus. +- Rufen Sie die nächste Middleware im Stapel auf. Wenn die aktuelle Middleware-Funktion den Request-Antwort-Zyklus nicht beendet, muss sie `next()` aufrufen, um die Kontrolle an die nächste Middleware-Funktion zu übergeben. Andernfalls bleibt die Anfrage hängen. @@ -100,7 +100,7 @@ const express = require('express'); const app = express(); const myLogger = function (req, res, next) { - console. og('LOGGED'); + console.og('LOGGED'); next(); }; @@ -220,7 +220,7 @@ Wenn Sie Ihre Middleware konfigurieren müssen, exportieren Sie eine Funktion, d Datei: `my-middleware.js` ```js -modul. xports = function (options) { +modul.xports = function (options) { return function (req, res, next) { // Implementierung der Middleware-Funktion basierend auf dem Options-Objekt next(); diff --git a/src/content/docs/de/4x/starter/basic-routing.mdx b/src/content/docs/de/4x/starter/basic-routing.mdx index 3b2a6d130d..dce7483626 100644 --- a/src/content/docs/de/4x/starter/basic-routing.mdx +++ b/src/content/docs/de/4x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Lernen Sie die Grundlagen des Routings in Express.js Anwendungen ke import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* bezieht sich darauf, wie eine Anwendung auf einen bestimmten Endpunkt antwortet , die eine URI (oder Pfad) und eine bestimmte HTTP-Request-Methode (GET, POST usw.) ist. +_Routing_ bezieht sich darauf, wie eine Anwendung auf einen bestimmten Endpunkt antwortet , die eine URI (oder Pfad) und eine bestimmte HTTP-Request-Methode (GET, POST usw.) ist. Jede Route kann eine oder mehrere Handler-Funktionen haben, die ausgeführt werden, wenn die Route übereinstimmt. @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); Wo: -* `app` ist eine Instanz von `express `. -* `METHOD` ist eine [HTTP-Anfrage-Methode](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in Kleinbuchstaben. -* `PATH` ist ein Pfad auf dem Server. -* `HANDLER` ist die Funktion, die ausgeführt wird, wenn die Route übereinstimmt. +- `app` ist eine Instanz von `express `. +- `METHOD` ist eine [HTTP-Anfrage-Methode](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in Kleinbuchstaben. +- `PATH` ist ein Pfad auf dem Server. +- `HANDLER` ist die Funktion, die ausgeführt wird, wenn die Route übereinstimmt. diff --git a/src/content/docs/de/4x/starter/examples.mdx b/src/content/docs/de/4x/starter/examples.mdx index 63df3debad..85b9e4ad97 100644 --- a/src/content/docs/de/4x/starter/examples.mdx +++ b/src/content/docs/de/4x/starter/examples.mdx @@ -5,41 +5,41 @@ description: Entdecken Sie eine Sammlung von Express.js Anwendungsbeispielen, di import Alert from '@components/primitives/Alert/Alert.astro'; -* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Authentifizierung mit Login und Passwort -* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - HTTP-Inhaltsaushandlung -* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Arbeiten mit Cookie-basierten Sitzungen -* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Arbeiten mit Cookies -* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Übertragung von Dateien zum Client -* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Arbeiten mit eingebetteten JavaScript-Vorlagen (ejs) -* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Fehlerseiten erstellen -* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Mit Fehler-Middleware arbeiten -* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Einfacher Anfragehandler -* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown als Template-Engine -* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Mit mehreren Express-Routern arbeiten -* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - Controller im MVC-Stil -* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Verfolgung der Online-Benutzeraktivität mit `online` und `redis` Paketen -* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Arbeiten mit Routenparametern -* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Mehrere HTTP-Operationen auf derselben Ressource -* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Routen mit einer Karte organisieren -* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Mit Route Middleware arbeiten -* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Routen pro Ressource organisieren -* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Such-API -* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - Benutzersitzungen -* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Serviere statische Dateien -* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Arbeiten mit virtuellen Hosts -* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Ansichten dynamisch rendern -* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Speichern von Daten im Anfrageobjekt zwischen Middleware-Aufrufen -* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Einfacher API-Dienst +- [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Authentifizierung mit Login und Passwort +- [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - HTTP-Inhaltsaushandlung +- [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Arbeiten mit Cookie-basierten Sitzungen +- [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Arbeiten mit Cookies +- [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Übertragung von Dateien zum Client +- [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Arbeiten mit eingebetteten JavaScript-Vorlagen (ejs) +- [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Fehlerseiten erstellen +- [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Mit Fehler-Middleware arbeiten +- [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Einfacher Anfragehandler +- [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown als Template-Engine +- [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Mit mehreren Express-Routern arbeiten +- [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - Controller im MVC-Stil +- [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Verfolgung der Online-Benutzeraktivität mit `online` und `redis` Paketen +- [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Arbeiten mit Routenparametern +- [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Mehrere HTTP-Operationen auf derselben Ressource +- [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Routen mit einer Karte organisieren +- [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Mit Route Middleware arbeiten +- [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Routen pro Ressource organisieren +- [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Such-API +- [session](https://github.com/expressjs/express/tree/4.x/examples/session) - Benutzersitzungen +- [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Serviere statische Dateien +- [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Arbeiten mit virtuellen Hosts +- [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Ansichten dynamisch rendern +- [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Speichern von Daten im Anfrageobjekt zwischen Middleware-Aufrufen +- [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Einfacher API-Dienst ## Zusätzliche Beispiele Dies sind einige zusätzliche Beispiele mit umfassenderen Integrationen. - Diese Informationen beziehen sich auf Sites, Produkte oder Module, die nicht vom - Expressjs Team betreut werden. Die Auflistung hier stellt keine Billigung oder Empfehlung des Projektteams von + Diese Informationen beziehen sich auf Sites, Produkte oder Module, die nicht vom Expressjs Team + betreut werden. Die Auflistung hier stellt keine Billigung oder Empfehlung des Projektteams von Expressjs dar. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Vollstack App mit Express und Next.js mit [Prisma](https://www.npmjs.com/package/prisma) als ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API mit Express in TypeScript mit [Prisma](https://www.npmjs.com/package/prisma) als ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Vollstack App mit Express und Next.js mit [Prisma](https://www.npmjs.com/package/prisma) als ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API mit Express in TypeScript mit [Prisma](https://www.npmjs.com/package/prisma) als ORM diff --git a/src/content/docs/de/4x/starter/generator.mdx b/src/content/docs/de/4x/starter/generator.mdx index 4559bace00..53c5930dbb 100644 --- a/src/content/docs/de/4x/starter/generator.mdx +++ b/src/content/docs/de/4x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force auf nicht leeres Verzeichnis ``` -Zum Beispiel erstellt das Folgende eine Express-App namens *myapp*. Die App wird in einem Ordner namens *myapp* im aktuellen Arbeitsverzeichnis erstellt und die View Engine wird auf Mops gesetzt: +Zum Beispiel erstellt das Folgende eine Express-App namens _myapp_. Die App wird in einem Ordner namens _myapp_ im aktuellen Arbeitsverzeichnis erstellt und die View Engine wird auf Mops gesetzt: ```bash $ express --view=pug myapp diff --git a/src/content/docs/de/4x/starter/hello-world.mdx b/src/content/docs/de/4x/starter/hello-world.mdx index 12f7b3f36c..14fbd320f5 100644 --- a/src/content/docs/de/4x/starter/hello-world.mdx +++ b/src/content/docs/de/4x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Eingebettet unten ist im Wesentlichen die einfachste Express-App, die Sie erstellen können. Es ist eine einzelne Datei-App -— *not* was Sie bekommen würden, wenn Sie den [Express-Generator](/en/starter/generator), welche +— _not_ was Sie bekommen würden, wenn Sie den [Express-Generator](/en/starter/generator), welche das Gerüst für eine vollständige Anwendung mit zahlreichen JavaScript-Dateien, Jade-Vorlagen und Unterverzeichnissen für verschiedene Zwecke erstellt. @@ -20,7 +20,7 @@ const app = express(); const port = 3000; app.get('/', (req, res) => { - res. end('Hallo World!'); + res.end('Hallo World!'); }); app.listen(port, () => { @@ -29,7 +29,7 @@ app.listen(port, () => { ``` Diese App startet einen Server und lauscht auf Port 3000 für Verbindungen. The app responds with "Hello World!" for requests -to the root URL (`/`) or *route*. Für jeden anderen Pfad wird es mit einem **404 Nicht gefunden** antworten. +to the root URL (`/`) or _route_. Für jeden anderen Pfad wird es mit einem **404 Nicht gefunden** antworten. ## Lokal laufen diff --git a/src/content/docs/de/5x/guide/behind-proxies.mdx b/src/content/docs/de/5x/guide/behind-proxies.mdx index 786e7aff5f..42b2f725fb 100644 --- a/src/content/docs/de/5x/guide/behind-proxies.mdx +++ b/src/content/docs/de/5x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ Wenn Sie auf `true` setzen, ist es wichtig sicherzustellen, dass der letzte Reve Eine IP-Adresse, ein Subnetz oder ein Array von IP-Adressen und Subnetzen, die darauf vertrauen, dass es sich um einen Reverse Proxy handelt. Die folgende Liste zeigt die vorkonfigurierten Subnetznamen an: -* loopback - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` Sie können IP-Adressen auf jede der folgenden Arten festlegen: @@ -90,12 +90,14 @@ Das Aktivieren von `trust proxy` hat folgende Auswirkungen: `X-Forwarded-Host` Header gesetzt wurde , die vom Client oder vom Proxy gesetzt werden kann.
  • - `X-Forwarded-Proto` kann vom Reverse Proxy gesetzt werden, um der App mitzuteilen, ob es `https` oder - `http` oder sogar ein ungültiger Name ist. Dieser Wert wird von [req.protocol]reflektiert (/en/api#req.protocol). + `X-Forwarded-Proto` kann vom Reverse Proxy gesetzt werden, um der App mitzuteilen, ob es `https` + oder `http` oder sogar ein ungültiger Name ist. Dieser Wert wird von [req.protocol]reflektiert + (/en/api#req.protocol).
  • Die Werte [req.ip](/en/api#req.ip) und [req.ips](/en/api#req.ips) werden auf der Basis der - Socket-Adresse und des `X-Forwarded-For` Headers gefüllt beginnend an der ersten nicht vertrauenswürdigen Adresse. + Socket-Adresse und des `X-Forwarded-For` Headers gefüllt beginnend an der ersten nicht + vertrauenswürdigen Adresse.
    • diff --git a/src/content/docs/de/5x/guide/error-handling.mdx b/src/content/docs/de/5x/guide/error-handling.mdx index d3d51364b4..9db119db26 100644 --- a/src/content/docs/de/5x/guide/error-handling.mdx +++ b/src/content/docs/de/5x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Verstehen Sie, wie Express.js Fehler im synchronen und asynchronen import Alert from '@components/primitives/Alert/Alert.astro'; -*Error Handling* bezieht sich darauf, wie Express Fehler fängt und verarbeitet, die +_Error Handling_ bezieht sich darauf, wie Express Fehler fängt und verarbeitet, die sowohl synchron als auch asynchron auftritt. Express kommt mit einem Standardfehler \-Handler, damit Sie nicht Ihren eigenen schreiben müssen, um loszulegen. @@ -30,11 +30,11 @@ catch and process them. Zum Beispiel: ```js app.get('/', (req, res, next) => { - fs. eadFile('/file-does-not-exist', (err, data) => { + fs.eadFile('/file-does-not-exist', (err, data) => { if (err) { next(err); // Fehler an Express übergeben. } else { - res. end(data); + res.end(data); } }); }); @@ -161,12 +161,12 @@ Setze die Umgebungsvariable `NODE_ENV` auf `production`, um die App im Produktio Wenn ein Fehler geschrieben wird, werden folgende Informationen zur Antwort hinzugefügt: -* Der `res.statusCode` wurde von `err.status` (oder `err.statusCode`) gesetzt. Wenn +- Der `res.statusCode` wurde von `err.status` (oder `err.statusCode`) gesetzt. Wenn sich dieser Wert außerhalb des 4xx oder 5xx Bereichs befindet, wird er auf 500 gesetzt. -* Die `res.statusMessage` wurde gemäß dem Statuscode gesetzt. -* Der Körper wird der HTML-Code der Statuscode-Nachricht sein, wenn in der Produktion +- Die `res.statusMessage` wurde gemäß dem Statuscode gesetzt. +- Der Körper wird der HTML-Code der Statuscode-Nachricht sein, wenn in der Produktion \-Umgebung, andernfalls 'err.stack' ist. -* Alle in einem `err.headers` Objekt angegebenen Header. +- Alle in einem `err.headers` Objekt angegebenen Header. Wenn du `next()` mit einem Fehler aufruft, nachdem du die Antwort geschrieben hast (z. B. wenn beim Streamen der @@ -212,12 +212,12 @@ const bodyParser = require('body-parser'); const methodOverride = require('method-override'); app.use( - bodyParser. rlencoded({ + bodyParser.rlencoded({ extended: true, }) ); app.use(bodyParser.json()); -app. se(methodOverride()); +app.se(methodOverride()); app.use((err, req, res, next) => { // Logik }); @@ -234,12 +234,12 @@ für Anfragen mit `XHR` und denen ohne folgende zu definieren: const bodyParser = require('body-parser'); const methodOverride = require('method-override'); -app. se( +app.se( bodyParser.urlencoded({ extended: true, }) ); -app. se(bodyParser.json()); +app.se(bodyParser.json()); app.use(methodOverride()); app.use(logErrors); app.use(clientErrorHandler); @@ -258,12 +258,12 @@ function logErrors(err, req, res, next) { Auch in diesem Beispiel wird `clientErrorHandler` wie folgt definiert; in diesem Fall wird der Fehler explizit an den nächsten weitergegeben. -Beachten Sie, dass, wenn *not* in einer Fehlerbehandlungsfunktion "Weiter" aufruft, Sie dafür verantwortlich sind, die Antwort zu schreiben (und zu beenden). Andernfalls werden diese Anträge "hängen" und sind nicht für die Müllsammlung berechtigt. +Beachten Sie, dass, wenn _not_ in einer Fehlerbehandlungsfunktion "Weiter" aufruft, Sie dafür verantwortlich sind, die Antwort zu schreiben (und zu beenden). Andernfalls werden diese Anträge "hängen" und sind nicht für die Müllsammlung berechtigt. ```js function clientErrorHandler(err, req, res, next) { if (req.xhr) { - res.status(500). end({ error: 'Something failed!' }); + res.status(500).end({ error: 'Something failed!' }); } else { next(err); } @@ -285,7 +285,7 @@ Wenn du einen Route-Handler mit mehreren Callback-Funktionen hast, kannst du den app.get( '/a_route_behind_paywall', (req, res, next) => { - if (!req.user. asPaid) { + if (!req.user.asPaid) { // weitere Bearbeitung dieser Anfrage next('route'); } else { @@ -293,9 +293,9 @@ app.get( } }, (req, res, next) => { - PaidContent. ind((err, doc) => { + PaidContent.ind((err, doc) => { if (err) return next(err); - res. son(doc); + res.son(doc); }); } ); diff --git a/src/content/docs/de/5x/guide/routing.mdx b/src/content/docs/de/5x/guide/routing.mdx index 709b3db818..58254d8832 100644 --- a/src/content/docs/de/5x/guide/routing.mdx +++ b/src/content/docs/de/5x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Lernen Sie, wie Sie Routen in Express.js Anwendungen definieren und import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* bezieht sich darauf, wie die Endpunkte einer Anwendung (URIs) auf Kundenanfragen reagieren. +_Routing_ bezieht sich darauf, wie die Endpunkte einer Anwendung (URIs) auf Kundenanfragen reagieren. Für eine Einführung in das Routing siehe [Basic routing](/en/starter/basic-routing). Du definierst Routing, indem du Methoden des Express `app` Objekts verwendest, die den HTTP-Methoden entsprechen; @@ -40,11 +40,11 @@ Der folgende Code ist ein Beispiel für Routen, die für die `GET` und die `POST ```js // GET Methode Route app.get('/', (req, res) => { - res. end('GET request to the homepage'); + res.end('GET request to the homepage'); }); // POST method route -app. ost('/', (req, res) => { +app.ost('/', (req, res) => { res.send('POST request to the homepage'); }); ``` @@ -52,7 +52,7 @@ app. ost('/', (req, res) => { Express unterstützt Methoden, die allen HTTP-Anfragemethoden entsprechen: `get`, `post` und so weiter. Für eine vollständige Liste siehe [app.METHOD](/en/5x/api#app.METHOD). -Es gibt eine spezielle Routing-Methode, `app.all()`, die benutzt wird, um Middleware-Funktionen an einem Pfad für *all* HTTP-Requestmethoden zu laden. Zum Beispiel wird der folgende Handler für Anfragen an die Route `"/secret"` ausgeführt, ob `GET` verwendet wird, `POST`, `PUT`, `DELETE`, oder jede andere HTTP-Anfragemethode, die im [http module]unterstützt wird (https://nodejs.org/api/http.html#http_http_methods). +Es gibt eine spezielle Routing-Methode, `app.all()`, die benutzt wird, um Middleware-Funktionen an einem Pfad für _all_ HTTP-Requestmethoden zu laden. Zum Beispiel wird der folgende Handler für Anfragen an die Route `"/secret"` ausgeführt, ob `GET` verwendet wird, `POST`, `PUT`, `DELETE`, oder jede andere HTTP-Anfragemethode, die im [http module]unterstützt wird (https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -244,10 +244,10 @@ Du kannst mehrere Callback-Funktionen bereitstellen, die sich wie [middleware](/ ```js app.get('/user/:id', (req, res, next) => { - if (req.params. d === '0') { + if (req.params.d === '0') { return next('route'); } - res. end(`User ${req.params.id}`); + res.end(`User ${req.params.id}`); }); app.get('/user/:id', (req, res) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { In diesem Beispiel: -* `GET /user/5` → behandelt durch die erste Route → sendet "Benutzer 5" -* `GET /user/0` → erste Routenaufrufe `next('route')`, überspringt zur nächsten passenden `/user/:id` Route +- `GET /user/5` → behandelt durch die erste Route → sendet "Benutzer 5" +- `GET /user/0` → erste Routenaufrufe `next('route')`, überspringt zur nächsten passenden `/user/:id` Route Routenhandler können in Form einer Funktion, eines Arrays von Funktionen oder Kombinationen beider sein, wie in den folgenden Beispielen gezeigt. @@ -276,11 +276,11 @@ Mehr als eine Callback-Funktion kann eine Route handhaben (stelle sicher, dass d app.get( '/example/b', (req, res, next) => { - Konsole. og('die Antwort wird von der nächsten Funktion gesendet. .'); + Konsole.og('die Antwort wird von der nächsten Funktion gesendet. .'); next(); }, (req, res) => { - res. end('Hallo von B!'); + res.end('Hallo von B!'); } ); ``` @@ -289,17 +289,17 @@ Ein Array von Callback-Funktionen kann eine Route handhaben. Zum Beispiel: ```js const cb0 = function (req, res, next) { - Konsole. og('CB0'); + Konsole.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; const cb2 = function (req, res) { - res. end('Hallo von C!'); + res.end('Hallo von C!'); }; app.get('/example/c', [cb0, cb1, cb2]); @@ -309,24 +309,24 @@ Eine Kombination aus unabhängigen Funktionen und Arrays von Funktionen kann ein ```js const cb0 = function (req, res, next) { - Konsole. og('CB0'); + Konsole.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; -App. et( +App.et( '/example/d', [cb0, cb1], (req, res, next) => { - Konsole. og('die Antwort wird von der nächsten Funktion gesendet. .'); + Konsole.og('die Antwort wird von der nächsten Funktion gesendet. .'); next(); }, (req, res) => { - res. end('Hallo von D!'); + res.end('Hallo von D!'); } ); ``` diff --git a/src/content/docs/de/5x/guide/using-middleware.mdx b/src/content/docs/de/5x/guide/using-middleware.mdx index 667105556e..adfe7537b4 100644 --- a/src/content/docs/de/5x/guide/using-middleware.mdx +++ b/src/content/docs/de/5x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express ist ein Routing- und Middleware-Webframework mit minimaler Funktionalität: Eine Express-Anwendung ist im Wesentlichen eine Reihe von Middleware-Funktionsaufrufen. -*Middleware* Funktionen sind Funktionen, die Zugriff auf das [request object](/en/5x/api#req) (`req`), das [Antwort-Objekt](/en/5x/api#res) (`res`) und die nächste Middleware-Funktion im Request-Antwort-Zyklus der Anwendung. Die nächste Middleware-Funktion wird üblicherweise durch eine Variable namens `next` bezeichnet. +_Middleware_ Funktionen sind Funktionen, die Zugriff auf das [request object](/en/5x/api#req) (`req`), das [Antwort-Objekt](/en/5x/api#res) (`res`) und die nächste Middleware-Funktion im Request-Antwort-Zyklus der Anwendung. Die nächste Middleware-Funktion wird üblicherweise durch eine Variable namens `next` bezeichnet. Middleware-Funktionen können folgende Aufgaben ausführen: -* Führe jeden Code aus. -* Änderungen an der Anfrage und den Antwort-Objekten vornehmen. -* Beende den Request-Antwort-Zyklus. -* Rufen Sie die nächste Middleware-Funktion im Stack auf. +- Führe jeden Code aus. +- Änderungen an der Anfrage und den Antwort-Objekten vornehmen. +- Beende den Request-Antwort-Zyklus. +- Rufen Sie die nächste Middleware-Funktion im Stack auf. Wenn die aktuelle Middleware-Funktion den Request-Antwort-Zyklus nicht beendet, muss sie `next()` aufrufen, um die Kontrolle an die nächste Middleware-Funktion zu übergeben. Andernfalls bleibt die Anfrage hängen. Eine Express-Anwendung kann folgende Arten von Middleware verwenden: -* [Middleware](#middleware.application) -* [Router-Level-Middleware](#middleware.router) -* [Error-handling middleware](#middleware.error-handling) -* [Integrierte Middleware](#middleware.built-in) -* [Middleware von Drittanbietern](#middleware.third-party) +- [Middleware](#middleware.application) +- [Router-Level-Middleware](#middleware.router) +- [Error-handling middleware](#middleware.error-handling) +- [Integrierte Middleware](#middleware.built-in) +- [Middleware von Drittanbietern](#middleware.third-party) Sie können Middleware auf Anwendungsebene und Routerebene mit einem optionalen Mount-Pfad laden. Sie können auch eine Reihe von Middleware-Funktionen zusammen laden, die einen Sub-Stack des Middleware-Systems an einem Mount-Punkt erzeugen. @@ -70,11 +70,11 @@ Es illustriert einen Middleware-Unterstapel, der Anfrageinformationen für jede app.use( '/user/:id', (req, res, next) => { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); }, (req, res, next) => { - console. og('Request Type:', req.method); + console.og('Request Type:', req.method); next(); } ); @@ -140,17 +140,17 @@ Dieses Beispiel zeigt ein Array mit einem Middleware-Sub-Stack an, das GET-Anfra ```js function logOriginalUrl(req, res, next) { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); } function logMethod(req, res, next) { - console.log('Request Type:', req. ethod); + console.log('Request Type:', req.ethod); next(); } const logStuff = [logOriginalUrl, logMethod]; -App. et('/user/:id', logStuff, (req, res, next) => { +App.et('/user/:id', logStuff, (req, res, next) => { res.send('User Info'); }); ``` @@ -246,7 +246,7 @@ App fällt. se('/admin', router, (req, res) => { -Bei der Fehlerbehebung der Middleware werden immer *vier* Argumente verwendet. Sie müssen vier Argumente angeben, um +Bei der Fehlerbehebung der Middleware werden immer _vier_ Argumente verwendet. Sie müssen vier Argumente angeben, um als Middleware-Funktion zu identifizieren. Selbst wenn du das `next` Objekt nicht verwenden musst, musst du es angeben, um die Signatur zu pflegen. Andernfalls wird das `next` Objekt als reguläre Middleware interpretiert und wird Fehler nicht bearbeiten. @@ -271,9 +271,9 @@ Ab Version 4.x ist Express nicht mehr abhängig von [Connect](https://github.com Express hat die folgenden integrierten Middleware-Funktionen: -* [express.static](/en/5x/api#express.static) dient statischen Assets wie HTML-Dateien, Bilder und so weiter. -* [express.json](/en/5x/api#express.json) analysiert eingehende Anfragen mit JSON Payloads. **HINWEIS: Verfügbar mit Express 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) analysiert eingehende Anfragen mit URL-kodierten Payloads. **HINWEIS: Verfügbar mit Express 4.16.0+** +- [express.static](/en/5x/api#express.static) dient statischen Assets wie HTML-Dateien, Bilder und so weiter. +- [express.json](/en/5x/api#express.json) analysiert eingehende Anfragen mit JSON Payloads. **HINWEIS: Verfügbar mit Express 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) analysiert eingehende Anfragen mit URL-kodierten Payloads. **HINWEIS: Verfügbar mit Express 4.16.0+** ## Drittanbieter-Middleware diff --git a/src/content/docs/de/5x/guide/using-template-engines.mdx b/src/content/docs/de/5x/guide/using-template-engines.mdx index 8fddcf43be..0a5b37a7c5 100644 --- a/src/content/docs/de/5x/guide/using-template-engines.mdx +++ b/src/content/docs/de/5x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Entdecken Sie, wie Sie Template-Engines wie Pug, Handlebars und EJS import Alert from '@components/primitives/Alert/Alert.astro'; -Eine *template engine* ermöglicht es Ihnen, statische Template-Dateien in Ihrer Anwendung zu verwenden. Zur Laufzeit ersetzt die Template-Engine +Eine _template engine_ ermöglicht es Ihnen, statische Template-Dateien in Ihrer Anwendung zu verwenden. Zur Laufzeit ersetzt die Template-Engine Variablen in einer Template-Datei mit aktuellen Werten und verwandelt die Vorlage in eine HTML-Datei, die an den Client gesendet wird. Dieser Ansatz erleichtert die Gestaltung einer HTML-Seite. @@ -13,9 +13,9 @@ Der [Express-Anwendungsgenerator](/en/starter/generator) verwendet [Pug](https:/ Um Template-Dateien zu rendern, setzen Sie folgende [Anwendungs-Einstellungen-Eigenschaften](/en/4x/api#app.set), in der Standardeinstellung `app.js`, die vom Generator erstellt wurde: -* `views`, das Verzeichnis, in dem sich die Template-Dateien befinden. Eg: `app.set('views', './views')`. +- `views`, das Verzeichnis, in dem sich die Template-Dateien befinden. Eg: `app.set('views', './views')`. Dies ist standardmäßig im Verzeichnis `views` im Root-Verzeichnis der Anwendung. -* `view engine`, die zu verwendende Template-Engine. Um zum Beispiel die Mückenvorlagen-Engine zu verwenden: `app.set('view engine', 'pug')`. +- `view engine`, die zu verwendende Template-Engine. Um zum Beispiel die Mückenvorlagen-Engine zu verwenden: `app.set('view engine', 'pug')`. Installieren Sie dann das entsprechende Template Engine npm Paket; zum Beispiel um Pug: diff --git a/src/content/docs/de/5x/guide/writing-middleware.mdx b/src/content/docs/de/5x/guide/writing-middleware.mdx index 984cc71804..477703c39b 100644 --- a/src/content/docs/de/5x/guide/writing-middleware.mdx +++ b/src/content/docs/de/5x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Erfahren Sie, wie Sie benutzerdefinierte Middleware-Funktionen für import Alert from '@components/primitives/Alert/Alert.astro'; -*Middleware* Funktionen sind Funktionen, die Zugriff auf das [request object](/en/5x/api#req) (`req`), die [Antwort-Objekt](/en/5x/api#res) (`res`) und die `next` Funktion im Request-Antwort-Zyklus der Anwendung. Die `next`-Funktion ist eine Funktion im Express-Router, der beim Aufruf die Middleware ausführt, die die aktuelle Middleware abfolgt. +_Middleware_ Funktionen sind Funktionen, die Zugriff auf das [request object](/en/5x/api#req) (`req`), die [Antwort-Objekt](/en/5x/api#res) (`res`) und die `next` Funktion im Request-Antwort-Zyklus der Anwendung. Die `next`-Funktion ist eine Funktion im Express-Router, der beim Aufruf die Middleware ausführt, die die aktuelle Middleware abfolgt. Middleware-Funktionen können folgende Aufgaben ausführen: -* Führe jeden Code aus. -* Änderungen an der Anfrage und den Antwort-Objekten vornehmen. -* Beende den Request-Antwort-Zyklus. -* Rufen Sie die nächste Middleware im Stapel auf. +- Führe jeden Code aus. +- Änderungen an der Anfrage und den Antwort-Objekten vornehmen. +- Beende den Request-Antwort-Zyklus. +- Rufen Sie die nächste Middleware im Stapel auf. Wenn die aktuelle Middleware-Funktion den Request-Antwort-Zyklus nicht beendet, muss sie `next()` aufrufen, um die Kontrolle an die nächste Middleware-Funktion zu übergeben. Andernfalls bleibt die Anfrage hängen. @@ -70,7 +70,7 @@ const express = require('express'); const app = express(); const myLogger = function (req, res, next) { - console. og('LOGGED'); + console.og('LOGGED'); next(); }; @@ -190,7 +190,7 @@ Wenn Sie Ihre Middleware konfigurieren müssen, exportieren Sie eine Funktion, d Datei: `my-middleware.js` ```js -modul. xports = function (options) { +modul.xports = function (options) { return function (req, res, next) { // Implementierung der Middleware-Funktion basierend auf dem Options-Objekt next(); diff --git a/src/content/docs/de/5x/starter/basic-routing.mdx b/src/content/docs/de/5x/starter/basic-routing.mdx index 3b2a6d130d..dce7483626 100644 --- a/src/content/docs/de/5x/starter/basic-routing.mdx +++ b/src/content/docs/de/5x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Lernen Sie die Grundlagen des Routings in Express.js Anwendungen ke import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* bezieht sich darauf, wie eine Anwendung auf einen bestimmten Endpunkt antwortet , die eine URI (oder Pfad) und eine bestimmte HTTP-Request-Methode (GET, POST usw.) ist. +_Routing_ bezieht sich darauf, wie eine Anwendung auf einen bestimmten Endpunkt antwortet , die eine URI (oder Pfad) und eine bestimmte HTTP-Request-Methode (GET, POST usw.) ist. Jede Route kann eine oder mehrere Handler-Funktionen haben, die ausgeführt werden, wenn die Route übereinstimmt. @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); Wo: -* `app` ist eine Instanz von `express `. -* `METHOD` ist eine [HTTP-Anfrage-Methode](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in Kleinbuchstaben. -* `PATH` ist ein Pfad auf dem Server. -* `HANDLER` ist die Funktion, die ausgeführt wird, wenn die Route übereinstimmt. +- `app` ist eine Instanz von `express `. +- `METHOD` ist eine [HTTP-Anfrage-Methode](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in Kleinbuchstaben. +- `PATH` ist ein Pfad auf dem Server. +- `HANDLER` ist die Funktion, die ausgeführt wird, wenn die Route übereinstimmt. diff --git a/src/content/docs/de/5x/starter/examples.mdx b/src/content/docs/de/5x/starter/examples.mdx index 82f5980728..815bf0c6f3 100644 --- a/src/content/docs/de/5x/starter/examples.mdx +++ b/src/content/docs/de/5x/starter/examples.mdx @@ -7,31 +7,31 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Diese Seite enthält eine Liste von Beispielen mit Express. -* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Authentifizierung mit Login und Passwort -* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - HTTP-Inhaltsaushandlung -* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Arbeiten mit Cookie-basierten Sitzungen -* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Arbeiten mit Cookies -* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Übertragung von Dateien zum Client -* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Arbeiten mit eingebetteten JavaScript-Vorlagen (ejs) -* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Fehlerseiten erstellen -* [error](https://github.com/expressjs/express/tree/master/examples/error) - Mit Fehler-Middleware arbeiten -* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Einfacher Anfragehandler -* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown als Template-Engine -* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Mit mehreren Express-Routern arbeiten -* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - Controller im MVC-Stil -* [online](https://github.com/expressjs/express/tree/master/examples/online) - Verfolgung der Online-Benutzeraktivität mit `online` und `redis` Paketen -* [params](https://github.com/expressjs/express/tree/master/examples/params) - Arbeiten mit Routenparametern -* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Mehrere HTTP-Operationen auf derselben Ressource -* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Routen mit einer Karte organisieren -* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Mit Route Middleware arbeiten -* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Routen pro Ressource organisieren -* [search](https://github.com/expressjs/express/tree/master/examples/search) - Such-API -* [session](https://github.com/expressjs/express/tree/master/examples/session) - Benutzersitzungen -* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Serviere statische Dateien -* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Arbeiten mit virtuellen Hosts -* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Ansichten dynamisch rendern -* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Speichern von Daten im Anfrageobjekt zwischen Middleware-Aufrufen -* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Einfacher API-Dienst +- [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Authentifizierung mit Login und Passwort +- [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - HTTP-Inhaltsaushandlung +- [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Arbeiten mit Cookie-basierten Sitzungen +- [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Arbeiten mit Cookies +- [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Übertragung von Dateien zum Client +- [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Arbeiten mit eingebetteten JavaScript-Vorlagen (ejs) +- [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Fehlerseiten erstellen +- [error](https://github.com/expressjs/express/tree/master/examples/error) - Mit Fehler-Middleware arbeiten +- [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Einfacher Anfragehandler +- [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown als Template-Engine +- [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Mit mehreren Express-Routern arbeiten +- [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - Controller im MVC-Stil +- [online](https://github.com/expressjs/express/tree/master/examples/online) - Verfolgung der Online-Benutzeraktivität mit `online` und `redis` Paketen +- [params](https://github.com/expressjs/express/tree/master/examples/params) - Arbeiten mit Routenparametern +- [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Mehrere HTTP-Operationen auf derselben Ressource +- [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Routen mit einer Karte organisieren +- [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Mit Route Middleware arbeiten +- [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Routen pro Ressource organisieren +- [search](https://github.com/expressjs/express/tree/master/examples/search) - Such-API +- [session](https://github.com/expressjs/express/tree/master/examples/session) - Benutzersitzungen +- [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Serviere statische Dateien +- [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Arbeiten mit virtuellen Hosts +- [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Ansichten dynamisch rendern +- [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Speichern von Daten im Anfrageobjekt zwischen Middleware-Aufrufen +- [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Einfacher API-Dienst ## Zusätzliche Beispiele @@ -45,5 +45,5 @@ Expressjs dar. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Vollstack App mit Express und Next.js mit [Prisma](https://www.npmjs.com/package/prisma) als ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API mit Express in TypeScript mit [Prisma](https://www.npmjs.com/package/prisma) als ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Vollstack App mit Express und Next.js mit [Prisma](https://www.npmjs.com/package/prisma) als ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API mit Express in TypeScript mit [Prisma](https://www.npmjs.com/package/prisma) als ORM diff --git a/src/content/docs/de/5x/starter/generator.mdx b/src/content/docs/de/5x/starter/generator.mdx index 4559bace00..53c5930dbb 100644 --- a/src/content/docs/de/5x/starter/generator.mdx +++ b/src/content/docs/de/5x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force auf nicht leeres Verzeichnis ``` -Zum Beispiel erstellt das Folgende eine Express-App namens *myapp*. Die App wird in einem Ordner namens *myapp* im aktuellen Arbeitsverzeichnis erstellt und die View Engine wird auf Mops gesetzt: +Zum Beispiel erstellt das Folgende eine Express-App namens _myapp_. Die App wird in einem Ordner namens _myapp_ im aktuellen Arbeitsverzeichnis erstellt und die View Engine wird auf Mops gesetzt: ```bash $ express --view=pug myapp diff --git a/src/content/docs/de/5x/starter/hello-world.mdx b/src/content/docs/de/5x/starter/hello-world.mdx index 12f7b3f36c..14fbd320f5 100644 --- a/src/content/docs/de/5x/starter/hello-world.mdx +++ b/src/content/docs/de/5x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Eingebettet unten ist im Wesentlichen die einfachste Express-App, die Sie erstellen können. Es ist eine einzelne Datei-App -— *not* was Sie bekommen würden, wenn Sie den [Express-Generator](/en/starter/generator), welche +— _not_ was Sie bekommen würden, wenn Sie den [Express-Generator](/en/starter/generator), welche das Gerüst für eine vollständige Anwendung mit zahlreichen JavaScript-Dateien, Jade-Vorlagen und Unterverzeichnissen für verschiedene Zwecke erstellt. @@ -20,7 +20,7 @@ const app = express(); const port = 3000; app.get('/', (req, res) => { - res. end('Hallo World!'); + res.end('Hallo World!'); }); app.listen(port, () => { @@ -29,7 +29,7 @@ app.listen(port, () => { ``` Diese App startet einen Server und lauscht auf Port 3000 für Verbindungen. The app responds with "Hello World!" for requests -to the root URL (`/`) or *route*. Für jeden anderen Pfad wird es mit einem **404 Nicht gefunden** antworten. +to the root URL (`/`) or _route_. Für jeden anderen Pfad wird es mit einem **404 Nicht gefunden** antworten. ## Lokal laufen diff --git a/src/content/docs/es/4x/guide/behind-proxies.mdx b/src/content/docs/es/4x/guide/behind-proxies.mdx index ec6a8e1c11..76d786f141 100644 --- a/src/content/docs/es/4x/guide/behind-proxies.mdx +++ b/src/content/docs/es/4x/guide/behind-proxies.mdx @@ -37,16 +37,16 @@ Cuando se establece en `true`, es importante asegurarse de que el último proxy Una dirección IP, subred, o un array de direcciones IP y subredes en las que confiar como un proxy inverso. La siguiente lista muestra los nombres de subred preconfigurados: -* bucle atrás - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- bucle atrás - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` Puede establecer direcciones IP de cualquiera de las siguientes maneras: ```js app.set('trust proxy', 'loopback'); // especificar una única subred app.set('trust proxy', 'loopback, 123.123.123.123'); // especificar una subred y una dirección -app. et('trust proxy', 'loopback, linklocal, uniquelocal'); // especifica múltiples subredes como CSV +app.et('trust proxy', 'loopback, linklocal, uniquelocal'); // especifica múltiples subredes como CSV app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // especifica múltiples subredes como un array ``` @@ -90,12 +90,14 @@ Habilitar `proxy de confianza` tendrá el siguiente impacto: `X-Forwarded-Host`, que puede ser definido por el cliente o por el proxy.
  • - `X-Forwarded-Proto` puede ser establecido por el proxy inverso para decirle a la aplicación si es `https` o - `http` o incluso un nombre inválido. Este valor se refleja en [req.protocol](/en/api#req.protocol). + `X-Forwarded-Proto` puede ser establecido por el proxy inverso para decirle a la aplicación si + es `https` o `http` o incluso un nombre inválido. Este valor se refleja en + [req.protocol](/en/api#req.protocol).
  • - Los valores [req.ip](/en/api#req.ip) y [req.ips](/en/api#req.ips) son poblados según la dirección del socket - y la cabecera `X-Forwarded-For`, comenzando en la primera dirección no confiable. + Los valores [req.ip](/en/api#req.ip) y [req.ips](/en/api#req.ips) son poblados según la + dirección del socket y la cabecera `X-Forwarded-For`, comenzando en la primera dirección no + confiable.
    • diff --git a/src/content/docs/es/4x/guide/error-handling.mdx b/src/content/docs/es/4x/guide/error-handling.mdx index c109279842..c899c51198 100644 --- a/src/content/docs/es/4x/guide/error-handling.mdx +++ b/src/content/docs/es/4x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Descargue cómo Express.js maneja errores en código sincrónico y import Alert from '@components/primitives/Alert/Alert.astro'; -*Error Handling* refers to how Express catches and processes errors that +_Error Handling_ refers to how Express catches and processes errors that occur both synchronously and asynchronously. Express viene con un manejador de error predeterminado , así que no necesitas escribir el tuyo propio para empezar. @@ -30,11 +30,11 @@ y middleware, debes pasarlos a la función `next()`, donde Express las capturar ```js app.get('/', (req, res, next) => { - fs. eadFile('/file-does-not-exist', (err, data) => { + fs.eadFile('/file-does-not-exist', (err, data) => { if (err) { next(err); // Pasar los errores a Express. } else { - res. end(data); + res.end(data); } }); }); @@ -103,10 +103,10 @@ que devuelven promesas. Por ejemplo: ```js app.get('/', (req, res, next) => { Promise.resolve() - . hen(() => { + .hen(() => { throw new Error('BROKEN'); }) - . atch(next); // Los errores se pasarán a Express. + .atch(next); // Los errores se pasarán a Express. }); ``` @@ -120,13 +120,13 @@ También podría utilizar una cadena de manejadores para depender de la captura ```js app.get('/', [ function (req, res, next) { - fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { - res.locals. ata = data; + fs.eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals.ata = data; siguiente(err); }); }, function (req, res) { - res. ocals.data = res.locals.data.split(',')[1]; + res.ocals.data = res.locals.data.split(',')[1]; res.send(res.locals.data); }, ]); @@ -161,12 +161,12 @@ Establece la variable de entorno `NODE_ENV` a `production`, para ejecutar la apl When an error is written, the following information is added to the response: -* El `res.statusCode` se establece desde `err.status` (o `err.statusCode`). Si +- El `res.statusCode` se establece desde `err.status` (o `err.statusCode`). Si este valor está fuera del rango 4xx o 5xx, se establecerá a 500. -* El `res.statusMessage` se establece de acuerdo al código de estado. -* El cuerpo será el HTML del mensaje del código de estado cuando en el entorno +- El `res.statusMessage` se establece de acuerdo al código de estado. +- El cuerpo será el HTML del mensaje del código de estado cuando en el entorno de producción, de lo contrario será `err.stack`. -* Cualquier cabecera especificada en un objeto `err.headers`. +- Cualquier cabecera especificada en un objeto `err.headers`. Si llama a `next()` con un error después de haber comenzado a escribir la respuesta (por ejemplo, si encuentras un error al transmitir la respuesta @@ -212,12 +212,12 @@ const bodyParser = require('body-parser'); const methodOverride = require('method-override'); app.use( - bodyParser. rlencoded({ + bodyParser.rlencoded({ extendido: true, }) ); app.use(bodyParser.json()); -app. se(methodOverride()); +app.se(methodOverride()); app.use((err, req, res, next) => { // lógica }); @@ -234,12 +234,12 @@ para las solicitudes realizadas usando `XHR` y las que no tienen: const bodyParser = require('body-parser'); const methodOverride = require('method-override'); -app. se( +app.se( bodyParser.urlencoded({ extendido: true, }) ); -app. se(bodyParser.json()); +app.se(bodyParser.json()); app.use(methodOverride()); app.use(logErrors); app.use(clientErrorHandler); @@ -258,12 +258,12 @@ function logErrors(err, req, res, next) { También en este ejemplo, `clientErrorHandler` se define de la siguiente manera; en este caso, el error se pasa explícitamente al siguiente. -Tenga en cuenta que cuando *no* llama "siguiente" en una función de manejo de errores, usted es responsable de escribir (y terminar) la respuesta. De lo contrario, esas solicitudes se "colgarán" y no serán elegibles para la recolección de basura. +Tenga en cuenta que cuando _no_ llama "siguiente" en una función de manejo de errores, usted es responsable de escribir (y terminar) la respuesta. De lo contrario, esas solicitudes se "colgarán" y no serán elegibles para la recolección de basura. ```js function clientErrorHandler(err, req, res, next) { if (req.xhr) { - res.status(500). end({ error: 'Something failed!' }); + res.status(500).end({ error: 'Something failed!' }); } else { next(err); } @@ -285,7 +285,7 @@ Si tiene un manejador de ruta con múltiples funciones de callback, puede utiliz app.get( '/a_route_behind_paywall', (req, res, next) => { - if (!req.user. asPaid) { + if (!req.user.asPaid) { // continúa manejando esta solicitud next('route'); } else { @@ -293,9 +293,9 @@ app.get( } }, (req, res, next) => { - PaidContent. ind((err, doc) => { + PaidContent.ind((err, doc) => { if (err) return next(err); - res. son(doc); + res.son(doc); }); } ); diff --git a/src/content/docs/es/4x/guide/routing.mdx b/src/content/docs/es/4x/guide/routing.mdx index 7735a472cf..a57c73637f 100644 --- a/src/content/docs/es/4x/guide/routing.mdx +++ b/src/content/docs/es/4x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Aprenda cómo definir y usar rutas en aplicaciones Express.js, incl import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* se refiere a cómo responden los extremos (URIs) de una aplicación a las peticiones del cliente. +_Routing_ se refiere a cómo responden los extremos (URIs) de una aplicación a las peticiones del cliente. Para una introducción al enrutamiento, consulte [Enrutamiento básico](/en/starter/basic-routing). Define enrutamiento usando métodos del objeto Express `app` que corresponden a métodos HTTP; @@ -26,7 +26,7 @@ const express = require('express'); const app = express(); // responden con "Hola mundo" cuando se hace una solicitud GET a la página de inicio -aplicación. et('/', (req, res) => { +aplicación.et('/', (req, res) => { res.send('hola mundo'); }); ``` @@ -40,11 +40,11 @@ El siguiente código es un ejemplo de rutas definidas para los métodos `GET` y ```js // Ruta del método GET app.get('/', (req, res) => { - res. end('GET request to the homepage'); + res.end('GET request to the homepage'); }); // método POST route -app. ost('/', (req, res) => { +app.ost('/', (req, res) => { res.send('POST request to the homepage'); }); ``` @@ -52,7 +52,7 @@ app. ost('/', (req, res) => { Express soporta métodos que corresponden a todos los métodos de petición HTTP: `get`, `post`, y así sucesivamente. Para una lista completa, vea [app.METHOD](/en/5x/api#app.METHOD). -Hay un método especial de enrutamiento, `app.all()`, usado para cargar funciones de middleware en una ruta para *all* métodos de petición HTTP. Por ejemplo, el siguiente manejador se ejecuta para peticiones a la ruta `"/secret"` ya sea usando `GET`, `POST`, `PUT`, `DELETE`, o cualquier otro método de solicitud HTTP soportado en el [módulo http](https://nodejs.org/api/http.html#http_http_methods). +Hay un método especial de enrutamiento, `app.all()`, usado para cargar funciones de middleware en una ruta para _all_ métodos de petición HTTP. Por ejemplo, el siguiente manejador se ejecuta para peticiones a la ruta `"/secret"` ya sea usando `GET`, `POST`, `PUT`, `DELETE`, o cualquier otro método de solicitud HTTP soportado en el [módulo http](https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -244,10 +244,10 @@ Puedes proporcionar múltiples funciones de callback que se comportan como [midd ```js app.get('/user/:id', (req, res, next) => { - if (req.params. d === '0') { + if (req.params.d === '0') { return next('route'); } - res. end(`Usuario ${req.params.id}`); + res.end(`Usuario ${req.params.id}`); }); app.get('/user/:id', (req, res) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { En este ejemplo: -* `GET /user/5` → manejado por primera ruta → envía "Usuario 5" -* `GET /user/0` → primera ruta llama a `next('ruta')`, saltando a la siguiente ruta `/user/:id` +- `GET /user/5` → manejado por primera ruta → envía "Usuario 5" +- `GET /user/0` → primera ruta llama a `next('ruta')`, saltando a la siguiente ruta `/user/:id` Los manejadores de rutas pueden ser en forma de una función, un array de funciones o combinaciones de ambos, como se muestra en los siguientes ejemplos. @@ -276,11 +276,11 @@ Más de una función de callback puede manejar una ruta (asegúrese de especific app.get( '/example/b', (req, res, next) => { - consola. og('la respuesta será enviada por la siguiente función . .'); + consola.og('la respuesta será enviada por la siguiente función . .'); siguiente(); }, (req, res) => { - res. end('Hola de B!'); + res.end('Hola de B!'); } ); ``` @@ -289,17 +289,17 @@ Una matriz de funciones de callback puede manejar una ruta. Por ejemplo: ```js const cb0 = function (req, res, next) { - consola. og('CB0'); + consola.og('CB0'); siguiente(); }; const cb1 = function (req, res, next) { - consola. og('CB1'); + consola.og('CB1'); siguiente(); }; const cb2 = function (req, res) { - res. end('Hola de C!'); + res.end('Hola de C!'); }; app.get('/example/c', [cb0, cb1, cb2]); @@ -309,24 +309,24 @@ Una combinación de funciones independientes y arreglos de funciones puede manej ```js const cb0 = function (req, res, next) { - consola. og('CB0'); + consola.og('CB0'); siguiente(); }; const cb1 = function (req, res, next) { - consola. og('CB1'); + consola.og('CB1'); siguiente(); }; -app. et( +app.et( '/example/d', [cb0, cb1], (req, res, next) => { - consola. og('la respuesta será enviada por la siguiente función . .'); + consola.og('la respuesta será enviada por la siguiente función . .'); siguiente(); }, (req, res) => { - res. end('Hola de D!'); + res.end('Hola de D!'); } ); ``` @@ -358,14 +358,14 @@ Aquí hay un ejemplo de manejadores encadenados de rutas que se definen usando ` app .route('/book') .get((req, res) => { - res. end('Obtén un libro al azar'); + res.end('Obtén un libro al azar'); }) - . ost((req, res) => { + .ost((req, res) => { res.send('Agregar un libro'); }) - . ut((req, res) => { + .ut((req, res) => { res.send('Actualizar el libro'); -}); + }); ``` ## express.Router @@ -378,21 +378,21 @@ Crea un archivo de enrutador llamado `birds.js` en el directorio de la aplicaci ```js const express = require('express'); -const router = express. outer(); +const router = express.outer(); // middleware que es específico para este router const timeLog = (req, res, next) => { - consola. og('Hora: ', Date.now()); + consola.og('Hora: ', Date.now()); siguiente(); -}; enrutador -. se(timeLog); +}; +enrutador.se(timeLog); // define la ruta de la página de inicio router.get('/', (req, res) => { - res. end('Página de inicio de aves'); + res.end('Página de inicio de aves'); }); // define la ruta -router. et('/about', (req, res) => { +router.et('/about', (req, res) => { res.send('About birds'); }); diff --git a/src/content/docs/es/4x/guide/using-middleware.mdx b/src/content/docs/es/4x/guide/using-middleware.mdx index 07d3417df7..a6852c622b 100644 --- a/src/content/docs/es/4x/guide/using-middleware.mdx +++ b/src/content/docs/es/4x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express es un framework web de enrutamiento y middleware que tiene una funcionalidad mínima propia: Una aplicación Express es esencialmente una serie de llamadas a funciones de middleware. -Las funciones *Middleware* son funciones que tienen acceso al [objeto de solicitud](/en/5x/api#req) (`req`), el [objeto de respuesta](/en/5x/api#res) (`res`), y la siguiente función de middleware en el ciclo de solicitud y respuesta de la aplicación. La siguiente función middleware se denota comúnmente por una variable llamada `next`. +Las funciones _Middleware_ son funciones que tienen acceso al [objeto de solicitud](/en/5x/api#req) (`req`), el [objeto de respuesta](/en/5x/api#res) (`res`), y la siguiente función de middleware en el ciclo de solicitud y respuesta de la aplicación. La siguiente función middleware se denota comúnmente por una variable llamada `next`. Las funciones de Middleware pueden realizar las siguientes tareas: -* Ejecutar cualquier código. -* Realizar cambios en la solicitud y en los objetos de respuesta. -* Terminar el ciclo de solicitud de respuesta. -* Llame a la siguiente función de middleware en la pila. +- Ejecutar cualquier código. +- Realizar cambios en la solicitud y en los objetos de respuesta. +- Terminar el ciclo de solicitud de respuesta. +- Llame a la siguiente función de middleware en la pila. Si la función actual de middleware no termina el ciclo de solicitud de respuesta, debe llamar a `next()` para pasar el control a la siguiente función de middleware. De lo contrario, la solicitud quedará colgada. Una aplicación Express puede utilizar los siguientes tipos de middleware: -* [Middleware de nivel de aplicación](#middleware.application) -* [Middleware de nivel superior](#middleware.router) -* [Middleware de manejo de errores](#middleware.error-handling) -* [Middleware incorporado](#middleware.built-in) -* [Middleware de terceros](#middleware.third-party) +- [Middleware de nivel de aplicación](#middleware.application) +- [Middleware de nivel superior](#middleware.router) +- [Middleware de manejo de errores](#middleware.error-handling) +- [Middleware incorporado](#middleware.built-in) +- [Middleware de terceros](#middleware.third-party) Puede cargar middleware de nivel de aplicación y de enrutador con una ruta de montaje opcional. También puede cargar una serie de funciones de middleware juntas, lo que crea un substack del sistema de middleware en un punto de montaje. @@ -70,11 +70,11 @@ Ilustra un substack de middleware que imprime la información de la petición pa app.use( '/user/:id', (req, res, next) => { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); }, (req, res, next) => { - consola. og('Tipo de solicitud:', req.method); + consola.og('Tipo de solicitud:', req.method); siguiente(); } ); @@ -88,16 +88,16 @@ Este ejemplo muestra un substack de middleware que maneja peticiones GET a la ru app.get( '/user/:id', (req, res, next) => { - console.log('ID:', req. arams.id); + console.log('ID:', req.arams.id); siguiente(); }, (req, res, next) => { - res. end('Información de usuario'); + res.end('Información de usuario'); } ); // manejador para la ruta /user/:id, que imprime el ID de usuario -app. et('/user/:id', (req, res, next) => { +app.et('/user/:id', (req, res, next) => { res.send(req.params.id); }); ``` @@ -140,17 +140,17 @@ Este ejemplo muestra una matriz con un substack de middleware que maneja peticio ```js function logOriginalUrl(req, res, next) { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); } function logMethod(req, res, next) { - console.log('Request Type:', req. ethod); + console.log('Request Type:', req.ethod); siguiente(); } const logStuff = [logOriginalUrl, logMethod]; -app. et('/user/:id', logStuff, (req, res, next) => { +app.et('/user/:id', logStuff, (req, res, next) => { res.send('Información de usuario'); }); ``` @@ -246,7 +246,7 @@ aplicación. se('/admin', router, (req, res) => { -Middleware manejado por errores siempre toma *four* argumentos. Debe proporcionar cuatro argumentos para +Middleware manejado por errores siempre toma _four_ argumentos. Debe proporcionar cuatro argumentos para identificarlo como una función de middleware que maneja errores. Incluso si no necesitas usar el objeto `next` , debes especificarlo para mantener la firma. De lo contrario, el objeto `siguiente` será interpretado como middleware regular y fallará al manejar errores. @@ -271,9 +271,9 @@ del middleware que anteriormente estaban incluidas con Express están ahora en m Express tiene las siguientes funciones de middleware incorporadas: -* [express.static](/en/5x/api#express.static) sirve activos estáticos como archivos HTML, imágenes, etc. -* [express.json](/en/5x/api#express.json) analiza las solicitudes entrantes con cargas útiles JSON. **NOTA: Disponible con Express 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) analiza las solicitudes entrantes con payloads codificados por URL. **NOTA: Disponible con Express 4.16.0+** +- [express.static](/en/5x/api#express.static) sirve activos estáticos como archivos HTML, imágenes, etc. +- [express.json](/en/5x/api#express.json) analiza las solicitudes entrantes con cargas útiles JSON. **NOTA: Disponible con Express 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) analiza las solicitudes entrantes con payloads codificados por URL. **NOTA: Disponible con Express 4.16.0+** ## Middleware de terceros diff --git a/src/content/docs/es/4x/guide/using-template-engines.mdx b/src/content/docs/es/4x/guide/using-template-engines.mdx index 0de07ab115..49818704ce 100644 --- a/src/content/docs/es/4x/guide/using-template-engines.mdx +++ b/src/content/docs/es/4x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Descubra cómo integrar y utilizar motores de plantillas como Pug, import Alert from '@components/primitives/Alert/Alert.astro'; -Un *template engine* le permite usar plantillas estáticas en su aplicación. En tiempo de ejecución, el motor de plantillas reemplaza variables +Un _template engine_ le permite usar plantillas estáticas en su aplicación. En tiempo de ejecución, el motor de plantillas reemplaza variables en un archivo de plantilla con valores reales. y transforma la plantilla en un archivo HTML enviado al cliente. Este enfoque facilita el diseño de una página HTML. @@ -13,9 +13,9 @@ El [generador de aplicaciones Express](/en/starter/generator) utiliza [Pug](http Para renderizar archivos de plantilla, establezca las siguientes [propiedades de configuración de aplicación](/en/4x/api#app.set), en el `app.js` por defecto creado por el generador: -* `vistas`, el directorio donde están ubicados los archivos de plantilla. Ej: `app.set('vistas', './views')`. +- `vistas`, el directorio donde están ubicados los archivos de plantilla. Ej: `app.set('vistas', './views')`. Esto por defecto es el directorio `views` en el directorio raíz de la aplicación. -* `ver engine`, el motor de plantillas a usar. Por ejemplo, para usar el motor de plantillas Pug: `app.set('view engine', 'pug')`. +- `ver engine`, el motor de plantillas a usar. Por ejemplo, para usar el motor de plantillas Pug: `app.set('view engine', 'pug')`. A continuación, instale el correspondiente paquete npm del motor de plantillas; por ejemplo para instalar Pug: diff --git a/src/content/docs/es/4x/guide/writing-middleware.mdx b/src/content/docs/es/4x/guide/writing-middleware.mdx index 6acd234dca..31b67b8555 100644 --- a/src/content/docs/es/4x/guide/writing-middleware.mdx +++ b/src/content/docs/es/4x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Aprenda cómo escribir funciones personalizadas de middleware para import Alert from '@components/primitives/Alert/Alert.astro'; -Las funciones *Middleware* son funciones que tienen acceso al [objeto de solicitud](/en/5x/api#req) (`req`), el [objeto de respuesta](/en/5x/api#res) (`res`), y la función `next` en el ciclo de solicitud y respuesta de la aplicación. La función `siguiente` es una función en el router Express que, cuando se invoca, ejecuta el middleware sucediendo al middleware actual. +Las funciones _Middleware_ son funciones que tienen acceso al [objeto de solicitud](/en/5x/api#req) (`req`), el [objeto de respuesta](/en/5x/api#res) (`res`), y la función `next` en el ciclo de solicitud y respuesta de la aplicación. La función `siguiente` es una función en el router Express que, cuando se invoca, ejecuta el middleware sucediendo al middleware actual. Las funciones de Middleware pueden realizar las siguientes tareas: -* Ejecutar cualquier código. -* Realizar cambios en la solicitud y en los objetos de respuesta. -* Terminar el ciclo de solicitud de respuesta. -* Llama al siguiente middleware en la pila. +- Ejecutar cualquier código. +- Realizar cambios en la solicitud y en los objetos de respuesta. +- Terminar el ciclo de solicitud de respuesta. +- Llama al siguiente middleware en la pila. Si la función actual de middleware no termina el ciclo de solicitud de respuesta, debe llamar a `next()` para pasar el control a la siguiente función de middleware. De lo contrario, la solicitud quedará colgada. @@ -40,8 +40,8 @@ La siguiente figura muestra los elementos de una llamada a una función de middl
    - HTTP argumento de respuesta a la función de middleware, llamada "res" por convención - . + HTTP argumento de respuesta a la función de middleware, llamada "res" + por convención .
    HTTP solicita un argumento a la función de middleware, llamado "req" por convención.
    @@ -100,7 +100,7 @@ const express = require('express'); const app = express(); const myLogger = function (req, res, next) { - consola. og('LOGGED'); + consola.og('LOGGED'); siguiente(); }; @@ -140,16 +140,16 @@ const express = require('express'); const app = express(); const requestTime = function (req, res, next) { - req. equestTime = Date.now(); + req.equestTime = Date.now(); next(); }; app.use(requestTime); -app. et('/', (req, res) => { +app.et('/', (req, res) => { let responseText = '¡Hola Mundo!
    '; responseText += `Solicitado en: ${req.requestTime}`; - res. end(responseText); + res.end(responseText); }); app.listen(3000); @@ -183,7 +183,7 @@ const cookieValidator = require('. cookieValidator'); const app = express(); async function validateCookies(req, res, next) { - await cookieValidator(req. ookies); + await cookieValidator(req.ookies); next(); } @@ -192,7 +192,7 @@ app.use(cookieParser()); app.use(validateCookies); // manejador de errores -app. se((err, req, res, next) => { +app.se((err, req, res, next) => { res.status(400).send(err.message); }); @@ -220,7 +220,7 @@ Si necesita que su middleware sea configurable, exporte una función que acepte Archivo: `my-middleware.js` ```js -módulo. xports = function (options) { +módulo.xports = function (options) { return function (req, res, next) { // Implementar la función middleware basada en el objeto de opciones siguiente(); diff --git a/src/content/docs/es/4x/starter/basic-routing.mdx b/src/content/docs/es/4x/starter/basic-routing.mdx index e6936dde33..51d6b399d2 100644 --- a/src/content/docs/es/4x/starter/basic-routing.mdx +++ b/src/content/docs/es/4x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Aprenda los fundamentos de la enrutamiento en aplicaciones Express. import Alert from '@components/primitives/Alert/Alert.astro'; -*Enrutamiento* se refiere a determinar cómo responde una aplicación a una solicitud de cliente a un punto final en particular, que es una URI (o ruta) y un método específico de petición HTTP (GET, POST, etc.). +_Enrutamiento_ se refiere a determinar cómo responde una aplicación a una solicitud de cliente a un punto final en particular, que es una URI (o ruta) y un método específico de petición HTTP (GET, POST, etc.). Cada ruta puede tener una o más funciones manejadoras, que se ejecutan cuando la ruta es igualada. @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); Donde: -* `app` es una instancia de `express`. -* `METHOD` es un [método de solicitud HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), en minúsculas. -* `PATH` es una ruta en el servidor. -* `HANDLER` es la función ejecutada cuando la ruta es coincidente. +- `app` es una instancia de `express`. +- `METHOD` es un [método de solicitud HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), en minúsculas. +- `PATH` es una ruta en el servidor. +- `HANDLER` es la función ejecutada cuando la ruta es coincidente. diff --git a/src/content/docs/es/4x/starter/examples.mdx b/src/content/docs/es/4x/starter/examples.mdx index 788006ca85..729ac5a379 100644 --- a/src/content/docs/es/4x/starter/examples.mdx +++ b/src/content/docs/es/4x/starter/examples.mdx @@ -5,41 +5,41 @@ description: Explore una colección de ejemplos de aplicaciones de Express.js qu import Alert from '@components/primitives/Alert/Alert.astro'; -* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Autenticación con nombre de usuario y contraseña -* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - negociación de contenido HTTP -* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Trabajando con sesiones basadas en cookies -* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Trabajando con galletas -* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transfiriendo archivos al cliente -* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Trabajando con plantillas JavaScript embebidas (ejs) -* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Creando páginas de error -* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Trabajando con middleware de error -* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Manejador de solicitudes simple -* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown como motor de plantillas -* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Trabajando con varios enrutadores Express -* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - Controladores estilo MVC -* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Tracking online user activity with `online` and `redis` packages -* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Trabajando con parámetros de ruta -* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Múltiples operaciones HTTP en el mismo recurso -* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organizar rutas usando un mapa -* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Trabajando con middleware de ruta -* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizando rutas por cada recurso -* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - API de búsqueda -* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - Sesiones de usuario -* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Subrayando archivos estáticos -* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Trabajando con hosts virtuales -* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Procesar dinámicamente las vistas -* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Saving data in request object between middleware calls -* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Servicio de API simple +- [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Autenticación con nombre de usuario y contraseña +- [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - negociación de contenido HTTP +- [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Trabajando con sesiones basadas en cookies +- [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Trabajando con galletas +- [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transfiriendo archivos al cliente +- [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Trabajando con plantillas JavaScript embebidas (ejs) +- [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Creando páginas de error +- [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Trabajando con middleware de error +- [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Manejador de solicitudes simple +- [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown como motor de plantillas +- [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Trabajando con varios enrutadores Express +- [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - Controladores estilo MVC +- [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Tracking online user activity with `online` and `redis` packages +- [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Trabajando con parámetros de ruta +- [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Múltiples operaciones HTTP en el mismo recurso +- [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organizar rutas usando un mapa +- [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Trabajando con middleware de ruta +- [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizando rutas por cada recurso +- [search](https://github.com/expressjs/express/tree/4.x/examples/search) - API de búsqueda +- [session](https://github.com/expressjs/express/tree/4.x/examples/session) - Sesiones de usuario +- [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Subrayando archivos estáticos +- [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Trabajando con hosts virtuales +- [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Procesar dinámicamente las vistas +- [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Saving data in request object between middleware calls +- [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Servicio de API simple ## Ejemplos adicionales Estos son algunos ejemplos adicionales con integraciones más amplias. - Esta información se refiere a sitios de terceros, productos o módulos que no son mantenidos por el equipo de - Expressjs. La lista aquí no constituye un aviso o recomendación del equipo de proyecto + Esta información se refiere a sitios de terceros, productos o módulos que no son mantenidos por el + equipo de Expressjs. La lista aquí no constituye un aviso o recomendación del equipo de proyecto Expressjs. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Aplicación completa con Express y Next.js usando [Prisma](https://www.npmjs.com/package/prisma) como ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - API REST con Express en TypeScript usando [Prisma](https://www.npmjs.com/package/prisma) como ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Aplicación completa con Express y Next.js usando [Prisma](https://www.npmjs.com/package/prisma) como ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - API REST con Express en TypeScript usando [Prisma](https://www.npmjs.com/package/prisma) como ORM diff --git a/src/content/docs/es/4x/starter/generator.mdx b/src/content/docs/es/4x/starter/generator.mdx index ef1a6d5949..2755232b43 100644 --- a/src/content/docs/es/4x/starter/generator.mdx +++ b/src/content/docs/es/4x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force en directorio no vacío ``` -Por ejemplo, lo siguiente crea una aplicación Express llamada *myapp*. La aplicación se creará en una carpeta llamada *myapp* en el directorio de trabajo actual y el motor de vistas se establecerá en Pug: +Por ejemplo, lo siguiente crea una aplicación Express llamada _myapp_. La aplicación se creará en una carpeta llamada _myapp_ en el directorio de trabajo actual y el motor de vistas se establecerá en Pug: ```bash $ express --view=pug myapp diff --git a/src/content/docs/es/4x/starter/hello-world.mdx b/src/content/docs/es/4x/starter/hello-world.mdx index 7a005e4fa7..5e74cf6bbb 100644 --- a/src/content/docs/es/4x/starter/hello-world.mdx +++ b/src/content/docs/es/4x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Incrustado a continuación es esencialmente la aplicación Express más simple que puede crear. Es una aplicación de archivo única -— *no* lo que obtendrías si utilizas el [generador Express](/en/starter/generator), que +— _no_ lo que obtendrías si utilizas el [generador Express](/en/starter/generator), que crea el andamio para una aplicación completa con numerosos archivos JavaScript, plantillas de Jade y subdirectorios para varios propósitos. @@ -20,7 +20,7 @@ const app = express(); const port = 3000; app.get('/', (req, res) => { - res. end('¡Hola Mundo!'); + res.end('¡Hola Mundo!'); }); app.listen(port, () => { @@ -29,7 +29,7 @@ app.listen(port, () => { ``` Esta aplicación inicia un servidor y escucha en el puerto 3000 para las conexiones. La aplicación responde con "¡Hola Mundo!" para las solicitudes -a la URL raíz (`/`) o *route*. Por cada otro camino, responderá con un **404 No Encontrado**. +a la URL raíz (`/`) o _route_. Por cada otro camino, responderá con un **404 No Encontrado**. ## Ejecutar localmente diff --git a/src/content/docs/es/5x/guide/behind-proxies.mdx b/src/content/docs/es/5x/guide/behind-proxies.mdx index ec6a8e1c11..76d786f141 100644 --- a/src/content/docs/es/5x/guide/behind-proxies.mdx +++ b/src/content/docs/es/5x/guide/behind-proxies.mdx @@ -37,16 +37,16 @@ Cuando se establece en `true`, es importante asegurarse de que el último proxy Una dirección IP, subred, o un array de direcciones IP y subredes en las que confiar como un proxy inverso. La siguiente lista muestra los nombres de subred preconfigurados: -* bucle atrás - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- bucle atrás - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` Puede establecer direcciones IP de cualquiera de las siguientes maneras: ```js app.set('trust proxy', 'loopback'); // especificar una única subred app.set('trust proxy', 'loopback, 123.123.123.123'); // especificar una subred y una dirección -app. et('trust proxy', 'loopback, linklocal, uniquelocal'); // especifica múltiples subredes como CSV +app.et('trust proxy', 'loopback, linklocal, uniquelocal'); // especifica múltiples subredes como CSV app.set('trust proxy', ['loopback', 'linklocal', 'uniquelocal']); // especifica múltiples subredes como un array ``` @@ -90,12 +90,14 @@ Habilitar `proxy de confianza` tendrá el siguiente impacto: `X-Forwarded-Host`, que puede ser definido por el cliente o por el proxy.
  • - `X-Forwarded-Proto` puede ser establecido por el proxy inverso para decirle a la aplicación si es `https` o - `http` o incluso un nombre inválido. Este valor se refleja en [req.protocol](/en/api#req.protocol). + `X-Forwarded-Proto` puede ser establecido por el proxy inverso para decirle a la aplicación si + es `https` o `http` o incluso un nombre inválido. Este valor se refleja en + [req.protocol](/en/api#req.protocol).
  • - Los valores [req.ip](/en/api#req.ip) y [req.ips](/en/api#req.ips) son poblados según la dirección del socket - y la cabecera `X-Forwarded-For`, comenzando en la primera dirección no confiable. + Los valores [req.ip](/en/api#req.ip) y [req.ips](/en/api#req.ips) son poblados según la + dirección del socket y la cabecera `X-Forwarded-For`, comenzando en la primera dirección no + confiable.
    • diff --git a/src/content/docs/es/5x/guide/error-handling.mdx b/src/content/docs/es/5x/guide/error-handling.mdx index c109279842..c899c51198 100644 --- a/src/content/docs/es/5x/guide/error-handling.mdx +++ b/src/content/docs/es/5x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Descargue cómo Express.js maneja errores en código sincrónico y import Alert from '@components/primitives/Alert/Alert.astro'; -*Error Handling* refers to how Express catches and processes errors that +_Error Handling_ refers to how Express catches and processes errors that occur both synchronously and asynchronously. Express viene con un manejador de error predeterminado , así que no necesitas escribir el tuyo propio para empezar. @@ -30,11 +30,11 @@ y middleware, debes pasarlos a la función `next()`, donde Express las capturar ```js app.get('/', (req, res, next) => { - fs. eadFile('/file-does-not-exist', (err, data) => { + fs.eadFile('/file-does-not-exist', (err, data) => { if (err) { next(err); // Pasar los errores a Express. } else { - res. end(data); + res.end(data); } }); }); @@ -103,10 +103,10 @@ que devuelven promesas. Por ejemplo: ```js app.get('/', (req, res, next) => { Promise.resolve() - . hen(() => { + .hen(() => { throw new Error('BROKEN'); }) - . atch(next); // Los errores se pasarán a Express. + .atch(next); // Los errores se pasarán a Express. }); ``` @@ -120,13 +120,13 @@ También podría utilizar una cadena de manejadores para depender de la captura ```js app.get('/', [ function (req, res, next) { - fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { - res.locals. ata = data; + fs.eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals.ata = data; siguiente(err); }); }, function (req, res) { - res. ocals.data = res.locals.data.split(',')[1]; + res.ocals.data = res.locals.data.split(',')[1]; res.send(res.locals.data); }, ]); @@ -161,12 +161,12 @@ Establece la variable de entorno `NODE_ENV` a `production`, para ejecutar la apl When an error is written, the following information is added to the response: -* El `res.statusCode` se establece desde `err.status` (o `err.statusCode`). Si +- El `res.statusCode` se establece desde `err.status` (o `err.statusCode`). Si este valor está fuera del rango 4xx o 5xx, se establecerá a 500. -* El `res.statusMessage` se establece de acuerdo al código de estado. -* El cuerpo será el HTML del mensaje del código de estado cuando en el entorno +- El `res.statusMessage` se establece de acuerdo al código de estado. +- El cuerpo será el HTML del mensaje del código de estado cuando en el entorno de producción, de lo contrario será `err.stack`. -* Cualquier cabecera especificada en un objeto `err.headers`. +- Cualquier cabecera especificada en un objeto `err.headers`. Si llama a `next()` con un error después de haber comenzado a escribir la respuesta (por ejemplo, si encuentras un error al transmitir la respuesta @@ -212,12 +212,12 @@ const bodyParser = require('body-parser'); const methodOverride = require('method-override'); app.use( - bodyParser. rlencoded({ + bodyParser.rlencoded({ extendido: true, }) ); app.use(bodyParser.json()); -app. se(methodOverride()); +app.se(methodOverride()); app.use((err, req, res, next) => { // lógica }); @@ -234,12 +234,12 @@ para las solicitudes realizadas usando `XHR` y las que no tienen: const bodyParser = require('body-parser'); const methodOverride = require('method-override'); -app. se( +app.se( bodyParser.urlencoded({ extendido: true, }) ); -app. se(bodyParser.json()); +app.se(bodyParser.json()); app.use(methodOverride()); app.use(logErrors); app.use(clientErrorHandler); @@ -258,12 +258,12 @@ function logErrors(err, req, res, next) { También en este ejemplo, `clientErrorHandler` se define de la siguiente manera; en este caso, el error se pasa explícitamente al siguiente. -Tenga en cuenta que cuando *no* llama "siguiente" en una función de manejo de errores, usted es responsable de escribir (y terminar) la respuesta. De lo contrario, esas solicitudes se "colgarán" y no serán elegibles para la recolección de basura. +Tenga en cuenta que cuando _no_ llama "siguiente" en una función de manejo de errores, usted es responsable de escribir (y terminar) la respuesta. De lo contrario, esas solicitudes se "colgarán" y no serán elegibles para la recolección de basura. ```js function clientErrorHandler(err, req, res, next) { if (req.xhr) { - res.status(500). end({ error: 'Something failed!' }); + res.status(500).end({ error: 'Something failed!' }); } else { next(err); } @@ -285,7 +285,7 @@ Si tiene un manejador de ruta con múltiples funciones de callback, puede utiliz app.get( '/a_route_behind_paywall', (req, res, next) => { - if (!req.user. asPaid) { + if (!req.user.asPaid) { // continúa manejando esta solicitud next('route'); } else { @@ -293,9 +293,9 @@ app.get( } }, (req, res, next) => { - PaidContent. ind((err, doc) => { + PaidContent.ind((err, doc) => { if (err) return next(err); - res. son(doc); + res.son(doc); }); } ); diff --git a/src/content/docs/es/5x/guide/routing.mdx b/src/content/docs/es/5x/guide/routing.mdx index 7735a472cf..a57c73637f 100644 --- a/src/content/docs/es/5x/guide/routing.mdx +++ b/src/content/docs/es/5x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Aprenda cómo definir y usar rutas en aplicaciones Express.js, incl import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* se refiere a cómo responden los extremos (URIs) de una aplicación a las peticiones del cliente. +_Routing_ se refiere a cómo responden los extremos (URIs) de una aplicación a las peticiones del cliente. Para una introducción al enrutamiento, consulte [Enrutamiento básico](/en/starter/basic-routing). Define enrutamiento usando métodos del objeto Express `app` que corresponden a métodos HTTP; @@ -26,7 +26,7 @@ const express = require('express'); const app = express(); // responden con "Hola mundo" cuando se hace una solicitud GET a la página de inicio -aplicación. et('/', (req, res) => { +aplicación.et('/', (req, res) => { res.send('hola mundo'); }); ``` @@ -40,11 +40,11 @@ El siguiente código es un ejemplo de rutas definidas para los métodos `GET` y ```js // Ruta del método GET app.get('/', (req, res) => { - res. end('GET request to the homepage'); + res.end('GET request to the homepage'); }); // método POST route -app. ost('/', (req, res) => { +app.ost('/', (req, res) => { res.send('POST request to the homepage'); }); ``` @@ -52,7 +52,7 @@ app. ost('/', (req, res) => { Express soporta métodos que corresponden a todos los métodos de petición HTTP: `get`, `post`, y así sucesivamente. Para una lista completa, vea [app.METHOD](/en/5x/api#app.METHOD). -Hay un método especial de enrutamiento, `app.all()`, usado para cargar funciones de middleware en una ruta para *all* métodos de petición HTTP. Por ejemplo, el siguiente manejador se ejecuta para peticiones a la ruta `"/secret"` ya sea usando `GET`, `POST`, `PUT`, `DELETE`, o cualquier otro método de solicitud HTTP soportado en el [módulo http](https://nodejs.org/api/http.html#http_http_methods). +Hay un método especial de enrutamiento, `app.all()`, usado para cargar funciones de middleware en una ruta para _all_ métodos de petición HTTP. Por ejemplo, el siguiente manejador se ejecuta para peticiones a la ruta `"/secret"` ya sea usando `GET`, `POST`, `PUT`, `DELETE`, o cualquier otro método de solicitud HTTP soportado en el [módulo http](https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -244,10 +244,10 @@ Puedes proporcionar múltiples funciones de callback que se comportan como [midd ```js app.get('/user/:id', (req, res, next) => { - if (req.params. d === '0') { + if (req.params.d === '0') { return next('route'); } - res. end(`Usuario ${req.params.id}`); + res.end(`Usuario ${req.params.id}`); }); app.get('/user/:id', (req, res) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { En este ejemplo: -* `GET /user/5` → manejado por primera ruta → envía "Usuario 5" -* `GET /user/0` → primera ruta llama a `next('ruta')`, saltando a la siguiente ruta `/user/:id` +- `GET /user/5` → manejado por primera ruta → envía "Usuario 5" +- `GET /user/0` → primera ruta llama a `next('ruta')`, saltando a la siguiente ruta `/user/:id` Los manejadores de rutas pueden ser en forma de una función, un array de funciones o combinaciones de ambos, como se muestra en los siguientes ejemplos. @@ -276,11 +276,11 @@ Más de una función de callback puede manejar una ruta (asegúrese de especific app.get( '/example/b', (req, res, next) => { - consola. og('la respuesta será enviada por la siguiente función . .'); + consola.og('la respuesta será enviada por la siguiente función . .'); siguiente(); }, (req, res) => { - res. end('Hola de B!'); + res.end('Hola de B!'); } ); ``` @@ -289,17 +289,17 @@ Una matriz de funciones de callback puede manejar una ruta. Por ejemplo: ```js const cb0 = function (req, res, next) { - consola. og('CB0'); + consola.og('CB0'); siguiente(); }; const cb1 = function (req, res, next) { - consola. og('CB1'); + consola.og('CB1'); siguiente(); }; const cb2 = function (req, res) { - res. end('Hola de C!'); + res.end('Hola de C!'); }; app.get('/example/c', [cb0, cb1, cb2]); @@ -309,24 +309,24 @@ Una combinación de funciones independientes y arreglos de funciones puede manej ```js const cb0 = function (req, res, next) { - consola. og('CB0'); + consola.og('CB0'); siguiente(); }; const cb1 = function (req, res, next) { - consola. og('CB1'); + consola.og('CB1'); siguiente(); }; -app. et( +app.et( '/example/d', [cb0, cb1], (req, res, next) => { - consola. og('la respuesta será enviada por la siguiente función . .'); + consola.og('la respuesta será enviada por la siguiente función . .'); siguiente(); }, (req, res) => { - res. end('Hola de D!'); + res.end('Hola de D!'); } ); ``` @@ -358,14 +358,14 @@ Aquí hay un ejemplo de manejadores encadenados de rutas que se definen usando ` app .route('/book') .get((req, res) => { - res. end('Obtén un libro al azar'); + res.end('Obtén un libro al azar'); }) - . ost((req, res) => { + .ost((req, res) => { res.send('Agregar un libro'); }) - . ut((req, res) => { + .ut((req, res) => { res.send('Actualizar el libro'); -}); + }); ``` ## express.Router @@ -378,21 +378,21 @@ Crea un archivo de enrutador llamado `birds.js` en el directorio de la aplicaci ```js const express = require('express'); -const router = express. outer(); +const router = express.outer(); // middleware que es específico para este router const timeLog = (req, res, next) => { - consola. og('Hora: ', Date.now()); + consola.og('Hora: ', Date.now()); siguiente(); -}; enrutador -. se(timeLog); +}; +enrutador.se(timeLog); // define la ruta de la página de inicio router.get('/', (req, res) => { - res. end('Página de inicio de aves'); + res.end('Página de inicio de aves'); }); // define la ruta -router. et('/about', (req, res) => { +router.et('/about', (req, res) => { res.send('About birds'); }); diff --git a/src/content/docs/es/5x/guide/using-middleware.mdx b/src/content/docs/es/5x/guide/using-middleware.mdx index 07d3417df7..a6852c622b 100644 --- a/src/content/docs/es/5x/guide/using-middleware.mdx +++ b/src/content/docs/es/5x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express es un framework web de enrutamiento y middleware que tiene una funcionalidad mínima propia: Una aplicación Express es esencialmente una serie de llamadas a funciones de middleware. -Las funciones *Middleware* son funciones que tienen acceso al [objeto de solicitud](/en/5x/api#req) (`req`), el [objeto de respuesta](/en/5x/api#res) (`res`), y la siguiente función de middleware en el ciclo de solicitud y respuesta de la aplicación. La siguiente función middleware se denota comúnmente por una variable llamada `next`. +Las funciones _Middleware_ son funciones que tienen acceso al [objeto de solicitud](/en/5x/api#req) (`req`), el [objeto de respuesta](/en/5x/api#res) (`res`), y la siguiente función de middleware en el ciclo de solicitud y respuesta de la aplicación. La siguiente función middleware se denota comúnmente por una variable llamada `next`. Las funciones de Middleware pueden realizar las siguientes tareas: -* Ejecutar cualquier código. -* Realizar cambios en la solicitud y en los objetos de respuesta. -* Terminar el ciclo de solicitud de respuesta. -* Llame a la siguiente función de middleware en la pila. +- Ejecutar cualquier código. +- Realizar cambios en la solicitud y en los objetos de respuesta. +- Terminar el ciclo de solicitud de respuesta. +- Llame a la siguiente función de middleware en la pila. Si la función actual de middleware no termina el ciclo de solicitud de respuesta, debe llamar a `next()` para pasar el control a la siguiente función de middleware. De lo contrario, la solicitud quedará colgada. Una aplicación Express puede utilizar los siguientes tipos de middleware: -* [Middleware de nivel de aplicación](#middleware.application) -* [Middleware de nivel superior](#middleware.router) -* [Middleware de manejo de errores](#middleware.error-handling) -* [Middleware incorporado](#middleware.built-in) -* [Middleware de terceros](#middleware.third-party) +- [Middleware de nivel de aplicación](#middleware.application) +- [Middleware de nivel superior](#middleware.router) +- [Middleware de manejo de errores](#middleware.error-handling) +- [Middleware incorporado](#middleware.built-in) +- [Middleware de terceros](#middleware.third-party) Puede cargar middleware de nivel de aplicación y de enrutador con una ruta de montaje opcional. También puede cargar una serie de funciones de middleware juntas, lo que crea un substack del sistema de middleware en un punto de montaje. @@ -70,11 +70,11 @@ Ilustra un substack de middleware que imprime la información de la petición pa app.use( '/user/:id', (req, res, next) => { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); }, (req, res, next) => { - consola. og('Tipo de solicitud:', req.method); + consola.og('Tipo de solicitud:', req.method); siguiente(); } ); @@ -88,16 +88,16 @@ Este ejemplo muestra un substack de middleware que maneja peticiones GET a la ru app.get( '/user/:id', (req, res, next) => { - console.log('ID:', req. arams.id); + console.log('ID:', req.arams.id); siguiente(); }, (req, res, next) => { - res. end('Información de usuario'); + res.end('Información de usuario'); } ); // manejador para la ruta /user/:id, que imprime el ID de usuario -app. et('/user/:id', (req, res, next) => { +app.et('/user/:id', (req, res, next) => { res.send(req.params.id); }); ``` @@ -140,17 +140,17 @@ Este ejemplo muestra una matriz con un substack de middleware que maneja peticio ```js function logOriginalUrl(req, res, next) { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); } function logMethod(req, res, next) { - console.log('Request Type:', req. ethod); + console.log('Request Type:', req.ethod); siguiente(); } const logStuff = [logOriginalUrl, logMethod]; -app. et('/user/:id', logStuff, (req, res, next) => { +app.et('/user/:id', logStuff, (req, res, next) => { res.send('Información de usuario'); }); ``` @@ -246,7 +246,7 @@ aplicación. se('/admin', router, (req, res) => { -Middleware manejado por errores siempre toma *four* argumentos. Debe proporcionar cuatro argumentos para +Middleware manejado por errores siempre toma _four_ argumentos. Debe proporcionar cuatro argumentos para identificarlo como una función de middleware que maneja errores. Incluso si no necesitas usar el objeto `next` , debes especificarlo para mantener la firma. De lo contrario, el objeto `siguiente` será interpretado como middleware regular y fallará al manejar errores. @@ -271,9 +271,9 @@ del middleware que anteriormente estaban incluidas con Express están ahora en m Express tiene las siguientes funciones de middleware incorporadas: -* [express.static](/en/5x/api#express.static) sirve activos estáticos como archivos HTML, imágenes, etc. -* [express.json](/en/5x/api#express.json) analiza las solicitudes entrantes con cargas útiles JSON. **NOTA: Disponible con Express 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) analiza las solicitudes entrantes con payloads codificados por URL. **NOTA: Disponible con Express 4.16.0+** +- [express.static](/en/5x/api#express.static) sirve activos estáticos como archivos HTML, imágenes, etc. +- [express.json](/en/5x/api#express.json) analiza las solicitudes entrantes con cargas útiles JSON. **NOTA: Disponible con Express 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) analiza las solicitudes entrantes con payloads codificados por URL. **NOTA: Disponible con Express 4.16.0+** ## Middleware de terceros diff --git a/src/content/docs/es/5x/guide/using-template-engines.mdx b/src/content/docs/es/5x/guide/using-template-engines.mdx index 0de07ab115..49818704ce 100644 --- a/src/content/docs/es/5x/guide/using-template-engines.mdx +++ b/src/content/docs/es/5x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Descubra cómo integrar y utilizar motores de plantillas como Pug, import Alert from '@components/primitives/Alert/Alert.astro'; -Un *template engine* le permite usar plantillas estáticas en su aplicación. En tiempo de ejecución, el motor de plantillas reemplaza variables +Un _template engine_ le permite usar plantillas estáticas en su aplicación. En tiempo de ejecución, el motor de plantillas reemplaza variables en un archivo de plantilla con valores reales. y transforma la plantilla en un archivo HTML enviado al cliente. Este enfoque facilita el diseño de una página HTML. @@ -13,9 +13,9 @@ El [generador de aplicaciones Express](/en/starter/generator) utiliza [Pug](http Para renderizar archivos de plantilla, establezca las siguientes [propiedades de configuración de aplicación](/en/4x/api#app.set), en el `app.js` por defecto creado por el generador: -* `vistas`, el directorio donde están ubicados los archivos de plantilla. Ej: `app.set('vistas', './views')`. +- `vistas`, el directorio donde están ubicados los archivos de plantilla. Ej: `app.set('vistas', './views')`. Esto por defecto es el directorio `views` en el directorio raíz de la aplicación. -* `ver engine`, el motor de plantillas a usar. Por ejemplo, para usar el motor de plantillas Pug: `app.set('view engine', 'pug')`. +- `ver engine`, el motor de plantillas a usar. Por ejemplo, para usar el motor de plantillas Pug: `app.set('view engine', 'pug')`. A continuación, instale el correspondiente paquete npm del motor de plantillas; por ejemplo para instalar Pug: diff --git a/src/content/docs/es/5x/guide/writing-middleware.mdx b/src/content/docs/es/5x/guide/writing-middleware.mdx index 20e58642b6..f1543b8c89 100644 --- a/src/content/docs/es/5x/guide/writing-middleware.mdx +++ b/src/content/docs/es/5x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Aprenda cómo escribir funciones personalizadas de middleware para import Alert from '@components/primitives/Alert/Alert.astro'; -Las funciones *Middleware* son funciones que tienen acceso al [objeto de solicitud](/en/5x/api#req) (`req`), el [objeto de respuesta](/en/5x/api#res) (`res`), y la función `next` en el ciclo de solicitud y respuesta de la aplicación. La función `siguiente` es una función en el router Express que, cuando se invoca, ejecuta el middleware sucediendo al middleware actual. +Las funciones _Middleware_ son funciones que tienen acceso al [objeto de solicitud](/en/5x/api#req) (`req`), el [objeto de respuesta](/en/5x/api#res) (`res`), y la función `next` en el ciclo de solicitud y respuesta de la aplicación. La función `siguiente` es una función en el router Express que, cuando se invoca, ejecuta el middleware sucediendo al middleware actual. Las funciones de Middleware pueden realizar las siguientes tareas: -* Ejecutar cualquier código. -* Realizar cambios en la solicitud y en los objetos de respuesta. -* Terminar el ciclo de solicitud de respuesta. -* Llama al siguiente middleware en la pila. +- Ejecutar cualquier código. +- Realizar cambios en la solicitud y en los objetos de respuesta. +- Terminar el ciclo de solicitud de respuesta. +- Llama al siguiente middleware en la pila. Si la función actual de middleware no termina el ciclo de solicitud de respuesta, debe llamar a `next()` para pasar el control a la siguiente función de middleware. De lo contrario, la solicitud quedará colgada. @@ -70,7 +70,7 @@ const express = require('express'); const app = express(); const myLogger = function (req, res, next) { - consola. og('LOGGED'); + consola.og('LOGGED'); siguiente(); }; @@ -110,16 +110,16 @@ const express = require('express'); const app = express(); const requestTime = function (req, res, next) { - req. equestTime = Date.now(); + req.equestTime = Date.now(); next(); }; app.use(requestTime); -app. et('/', (req, res) => { +app.et('/', (req, res) => { let responseText = '¡Hola Mundo!
    '; responseText += `Solicitado en: ${req.requestTime}`; - res. end(responseText); + res.end(responseText); }); app.listen(3000); @@ -153,7 +153,7 @@ const cookieValidator = require('. cookieValidator'); const app = express(); async function validateCookies(req, res, next) { - await cookieValidator(req. ookies); + await cookieValidator(req.ookies); next(); } @@ -162,7 +162,7 @@ app.use(cookieParser()); app.use(validateCookies); // manejador de errores -app. se((err, req, res, next) => { +app.se((err, req, res, next) => { res.status(400).send(err.message); }); @@ -190,7 +190,7 @@ Si necesita que su middleware sea configurable, exporte una función que acepte Archivo: `my-middleware.js` ```js -módulo. xports = function (options) { +módulo.xports = function (options) { return function (req, res, next) { // Implementar la función middleware basada en el objeto de opciones siguiente(); diff --git a/src/content/docs/es/5x/starter/basic-routing.mdx b/src/content/docs/es/5x/starter/basic-routing.mdx index e6936dde33..51d6b399d2 100644 --- a/src/content/docs/es/5x/starter/basic-routing.mdx +++ b/src/content/docs/es/5x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Aprenda los fundamentos de la enrutamiento en aplicaciones Express. import Alert from '@components/primitives/Alert/Alert.astro'; -*Enrutamiento* se refiere a determinar cómo responde una aplicación a una solicitud de cliente a un punto final en particular, que es una URI (o ruta) y un método específico de petición HTTP (GET, POST, etc.). +_Enrutamiento_ se refiere a determinar cómo responde una aplicación a una solicitud de cliente a un punto final en particular, que es una URI (o ruta) y un método específico de petición HTTP (GET, POST, etc.). Cada ruta puede tener una o más funciones manejadoras, que se ejecutan cuando la ruta es igualada. @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); Donde: -* `app` es una instancia de `express`. -* `METHOD` es un [método de solicitud HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), en minúsculas. -* `PATH` es una ruta en el servidor. -* `HANDLER` es la función ejecutada cuando la ruta es coincidente. +- `app` es una instancia de `express`. +- `METHOD` es un [método de solicitud HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), en minúsculas. +- `PATH` es una ruta en el servidor. +- `HANDLER` es la función ejecutada cuando la ruta es coincidente. diff --git a/src/content/docs/es/5x/starter/examples.mdx b/src/content/docs/es/5x/starter/examples.mdx index 6fb4611e9c..7584ec7480 100644 --- a/src/content/docs/es/5x/starter/examples.mdx +++ b/src/content/docs/es/5x/starter/examples.mdx @@ -7,31 +7,31 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Esta página contiene una lista de ejemplos usando Express. -* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Autenticación con nombre de usuario y contraseña -* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - negociación de contenido HTTP -* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Trabajando con sesiones basadas en cookies -* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Trabajando con galletas -* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transfiriendo archivos al cliente -* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Trabajando con plantillas JavaScript embebidas (ejs) -* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Creando páginas de error -* [error](https://github.com/expressjs/express/tree/master/examples/error) - Trabajando con middleware de error -* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Manejador de solicitudes simple -* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown como motor de plantillas -* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Trabajando con varios enrutadores Express -* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - Controladores estilo MVC -* [online](https://github.com/expressjs/express/tree/master/examples/online) - Tracking online user activity with `online` and `redis` packages -* [params](https://github.com/expressjs/express/tree/master/examples/params) - Trabajando con parámetros de ruta -* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Múltiples operaciones HTTP en el mismo recurso -* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organizar rutas usando un mapa -* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Trabajando con middleware de ruta -* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizando rutas por cada recurso -* [search](https://github.com/expressjs/express/tree/master/examples/search) - API de búsqueda -* [session](https://github.com/expressjs/express/tree/master/examples/session) - Sesiones de usuario -* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Subrayando archivos estáticos -* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Trabajando con hosts virtuales -* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Procesar dinámicamente las vistas -* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Saving data in request object between middleware calls -* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Servicio de API simple +- [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Autenticación con nombre de usuario y contraseña +- [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - negociación de contenido HTTP +- [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Trabajando con sesiones basadas en cookies +- [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Trabajando con galletas +- [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transfiriendo archivos al cliente +- [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Trabajando con plantillas JavaScript embebidas (ejs) +- [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Creando páginas de error +- [error](https://github.com/expressjs/express/tree/master/examples/error) - Trabajando con middleware de error +- [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Manejador de solicitudes simple +- [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown como motor de plantillas +- [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Trabajando con varios enrutadores Express +- [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - Controladores estilo MVC +- [online](https://github.com/expressjs/express/tree/master/examples/online) - Tracking online user activity with `online` and `redis` packages +- [params](https://github.com/expressjs/express/tree/master/examples/params) - Trabajando con parámetros de ruta +- [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Múltiples operaciones HTTP en el mismo recurso +- [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organizar rutas usando un mapa +- [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Trabajando con middleware de ruta +- [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizando rutas por cada recurso +- [search](https://github.com/expressjs/express/tree/master/examples/search) - API de búsqueda +- [session](https://github.com/expressjs/express/tree/master/examples/session) - Sesiones de usuario +- [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Subrayando archivos estáticos +- [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Trabajando con hosts virtuales +- [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Procesar dinámicamente las vistas +- [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Saving data in request object between middleware calls +- [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Servicio de API simple ## Ejemplos adicionales @@ -45,5 +45,5 @@ Expressjs. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Aplicación completa con Express y Next.js usando [Prisma](https://www.npmjs.com/package/prisma) como ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - API REST con Express en TypeScript usando [Prisma](https://www.npmjs.com/package/prisma) como ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Aplicación completa con Express y Next.js usando [Prisma](https://www.npmjs.com/package/prisma) como ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - API REST con Express en TypeScript usando [Prisma](https://www.npmjs.com/package/prisma) como ORM diff --git a/src/content/docs/es/5x/starter/generator.mdx b/src/content/docs/es/5x/starter/generator.mdx index ef1a6d5949..2755232b43 100644 --- a/src/content/docs/es/5x/starter/generator.mdx +++ b/src/content/docs/es/5x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force en directorio no vacío ``` -Por ejemplo, lo siguiente crea una aplicación Express llamada *myapp*. La aplicación se creará en una carpeta llamada *myapp* en el directorio de trabajo actual y el motor de vistas se establecerá en Pug: +Por ejemplo, lo siguiente crea una aplicación Express llamada _myapp_. La aplicación se creará en una carpeta llamada _myapp_ en el directorio de trabajo actual y el motor de vistas se establecerá en Pug: ```bash $ express --view=pug myapp diff --git a/src/content/docs/es/5x/starter/hello-world.mdx b/src/content/docs/es/5x/starter/hello-world.mdx index 7a005e4fa7..5e74cf6bbb 100644 --- a/src/content/docs/es/5x/starter/hello-world.mdx +++ b/src/content/docs/es/5x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Incrustado a continuación es esencialmente la aplicación Express más simple que puede crear. Es una aplicación de archivo única -— *no* lo que obtendrías si utilizas el [generador Express](/en/starter/generator), que +— _no_ lo que obtendrías si utilizas el [generador Express](/en/starter/generator), que crea el andamio para una aplicación completa con numerosos archivos JavaScript, plantillas de Jade y subdirectorios para varios propósitos. @@ -20,7 +20,7 @@ const app = express(); const port = 3000; app.get('/', (req, res) => { - res. end('¡Hola Mundo!'); + res.end('¡Hola Mundo!'); }); app.listen(port, () => { @@ -29,7 +29,7 @@ app.listen(port, () => { ``` Esta aplicación inicia un servidor y escucha en el puerto 3000 para las conexiones. La aplicación responde con "¡Hola Mundo!" para las solicitudes -a la URL raíz (`/`) o *route*. Por cada otro camino, responderá con un **404 No Encontrado**. +a la URL raíz (`/`) o _route_. Por cada otro camino, responderá con un **404 No Encontrado**. ## Ejecutar localmente diff --git a/src/content/docs/fr/4x/guide/behind-proxies.mdx b/src/content/docs/fr/4x/guide/behind-proxies.mdx index 1eabee667b..aa17a36f63 100644 --- a/src/content/docs/fr/4x/guide/behind-proxies.mdx +++ b/src/content/docs/fr/4x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ Lorsque vous définissez sur `true`, il est important de s'assurer que le dernie Une adresse IP, un sous-réseau ou un tableau d'adresses IP et de sous-réseaux à confier comme étant un proxy inverse. La liste suivante montre les noms de sous-réseaux pré-configurés : -* loopback - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` Vous pouvez définir les adresses IP de l'une des façons suivantes : @@ -86,16 +86,18 @@ Activer `trust proxy` aura l'impact suivant :
    • - La valeur de [req.hostname](/en/api#req.hostname) est dérivée de la valeur définie dans l'en-tête - `X-Forwarded-Host`, qui peut être définie par le client ou par le proxy. + La valeur de [req.hostname](/en/api#req.hostname) est dérivée de la valeur définie dans + l'en-tête `X-Forwarded-Host`, qui peut être définie par le client ou par le proxy.
    • - `X-Forwarded-Proto` peut être défini par le proxy inverse pour dire à l'application si c'est `https` ou - `http` ou même un nom invalide. Cette valeur est reflétée par [req.protocol](/en/api#req.protocol). + `X-Forwarded-Proto` peut être défini par le proxy inverse pour dire à l'application si c'est + `https` ou `http` ou même un nom invalide. Cette valeur est reflétée par + [req.protocol](/en/api#req.protocol).
    • - Les valeurs [req.ip](/en/api#req.ip) et [req.ips](/en/api#req.ips) sont remplies en fonction de l'adresse du socket - et de l'en-tête `X-Forwarded-For`, à partir de la première adresse non fiable. + Les valeurs [req.ip](/en/api#req.ip) et [req.ips](/en/api#req.ips) sont remplies en fonction de + l'adresse du socket et de l'en-tête `X-Forwarded-For`, à partir de la première adresse non + fiable.
    diff --git a/src/content/docs/fr/4x/guide/error-handling.mdx b/src/content/docs/fr/4x/guide/error-handling.mdx index 1ef9f11421..0bcd847565 100644 --- a/src/content/docs/fr/4x/guide/error-handling.mdx +++ b/src/content/docs/fr/4x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Comprenez comment Express.js gère les erreurs dans le code synchro import Alert from '@components/primitives/Alert/Alert.astro'; -*Error Handling* fait référence à la façon dont Express attrape et traite les erreurs que +_Error Handling_ fait référence à la façon dont Express attrape et traite les erreurs que se produisent de manière synchronisée et asynchrone. Express comes with a default error handler so you don't need to write your own to get started. @@ -30,11 +30,11 @@ catch and process them. Par exemple : ```js app.get('/', (req, res, next) => { - fs. eadFile('/file-does-not-exist', (err, data) => { + fs.eadFile('/file-does-not-exist', (err, data) => { if (err) { next(err); // Passez des erreurs à Express. } else { - res. end(data); + res.end(data); } }); }); @@ -103,10 +103,10 @@ qui renvoient des promesses. Par exemple : ```js app.get('/', (req, res, next) => { Promise.resolve() - . hen(() => { + .hen(() => { throw new Error('BROKEN'); }) - . atch(next); // Les erreurs seront passées à Express. + .atch(next); // Les erreurs seront passées à Express. }); ``` @@ -161,12 +161,12 @@ Définissez la variable d'environnement `NODE_ENV` à `production`, pour exécut Lorsqu'une erreur est écrite, les informations suivantes sont ajoutées à la réponse : -* Le `res.statusCode` est défini à partir de `err.status` (ou `err.statusCode`). Si +- Le `res.statusCode` est défini à partir de `err.status` (ou `err.statusCode`). Si cette valeur est en dehors de la plage 4xx ou 5xx, elle sera définie à 500. -* Le `res.statusMessage` est défini selon le code de statut. -* Le corps sera le HTML du message de code de statut lorsque l'environnement de production +- Le `res.statusMessage` est défini selon le code de statut. +- Le corps sera le HTML du message de code de statut lorsque l'environnement de production , sinon sera `err.stack`. -* N'importe quel en-tête spécifié dans un objet `err.headers`. +- N'importe quel en-tête spécifié dans un objet `err.headers`. Si vous appelez `next()` avec une erreur après avoir commencé à écrire la réponse (par exemple, si vous rencontrez une erreur lors du streaming de la réponse @@ -212,12 +212,12 @@ const bodyParser = require('body-parser'); const methodOverride = require('method-override'); app.use( - bodyParser. rlencoded({ + bodyParser.rlencoded({ étendu: true, }) ); app.use(bodyParser.json()); -app. se(methodOverride()); +app.se(methodOverride()); app.use((err, req, res, next) => { // logique }); @@ -234,12 +234,12 @@ pour les requêtes faites en utilisant `XHR` et ceux sans : const bodyParser = require('body-parser'); const methodOverride = require('method-override'); -application. se( +application.se( bodyParser.urlencoded({ étendu: true, }) ); -app. se(bodyParser.json()); +app.se(bodyParser.json()); app.use(methodOverride()); app.use(logErrors); app.use(clientErrorHandler); @@ -258,12 +258,12 @@ function logErrors(err, req, res, next) { Aussi dans cet exemple, `clientErrorHandler` est défini comme suit ; dans ce cas, l'erreur est explicitement passée au suivant. -Notez que lorsque *not* appelez "next" dans une fonction de gestion des erreurs, vous êtes responsable de l'écriture (et de la fin) de la réponse. Sinon, ces demandes seront « bloquées » et ne seront pas admissibles au ramassage des déchets. +Notez que lorsque _not_ appelez "next" dans une fonction de gestion des erreurs, vous êtes responsable de l'écriture (et de la fin) de la réponse. Sinon, ces demandes seront « bloquées » et ne seront pas admissibles au ramassage des déchets. ```js function clientErrorHandler(err, req, res, next) { if (req.xhr) { - res.status(500). end({ error: 'Quelque chose a échoué!' }); + res.status(500).end({ error: 'Quelque chose a échoué!' }); } else { next(err); } diff --git a/src/content/docs/fr/4x/guide/routing.mdx b/src/content/docs/fr/4x/guide/routing.mdx index 65e3d690e4..3c009b7b16 100644 --- a/src/content/docs/fr/4x/guide/routing.mdx +++ b/src/content/docs/fr/4x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Apprenez à définir et utiliser des routes dans les applications E import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* indique comment les terminaux (URIs) d'une application répondent aux requêtes du client. +_Routing_ indique comment les terminaux (URIs) d'une application répondent aux requêtes du client. Pour une introduction au routage, voir [Routage de base](/en/starter/basic-routing). Vous définissez le routage à l'aide des méthodes de l'objet Express `app` qui correspondent aux méthodes HTTP; @@ -52,7 +52,7 @@ app. ost('/', (req, res) => { Express supporte les méthodes qui correspondent à toutes les méthodes de requête HTTP : `get`, `post`, et ainsi de suite. Pour une liste complète, voir [app.METHOD](/en/5x/api#app.METHOD). -Il y a une méthode de routage spéciale, `app.all()`, utilisée pour charger les fonctions du middleware à un chemin pour *toutes* les méthodes de requête HTTP. Par exemple, le gestionnaire suivant est exécuté pour les requêtes vers la route `"/secret"` si vous utilisez `GET`, `POST`, `PUT`, `DELETE`, ou toute autre méthode de requête HTTP supportée dans le module [http](https://nodejs.org/api/http.html#http_http_methods). +Il y a une méthode de routage spéciale, `app.all()`, utilisée pour charger les fonctions du middleware à un chemin pour _toutes_ les méthodes de requête HTTP. Par exemple, le gestionnaire suivant est exécuté pour les requêtes vers la route `"/secret"` si vous utilisez `GET`, `POST`, `PUT`, `DELETE`, ou toute autre méthode de requête HTTP supportée dans le module [http](https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { Dans cet exemple : -* `GET /user/5` → géré par la première route → envoie "Utilisateur 5" -* `GET /user/0` → première route appelle `next('route')`, passe à la prochaine route correspondant à `/user/:id` +- `GET /user/5` → géré par la première route → envoie "Utilisateur 5" +- `GET /user/0` → première route appelle `next('route')`, passe à la prochaine route correspondant à `/user/:id` Les gestionnaires de routes peuvent être sous la forme d'une fonction, d'un tableau de fonctions, ou de combinaisons des deux, comme indiqué dans les exemples suivants. @@ -276,7 +276,7 @@ Plus d'une fonction de rappel peut gérer une route (assurez-vous de spécifier app.get( '/example/b', (req, res, next) => { - console. og('la réponse sera envoyée par la fonction suivante . .'); + console.og('la réponse sera envoyée par la fonction suivante . .'); next(); }, (req, res) => { @@ -289,12 +289,12 @@ Un tableau de fonctions de rappel peut gérer une route. Par exemple : ```js const cb0 = function (req, res, suivant) { - console. og('CB0'); + console.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; @@ -309,24 +309,24 @@ Une combinaison de fonctions indépendantes et de tableaux de fonctions peut gé ```js const cb0 = function (req, res, suivant) { - console. og('CB0'); + console.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); suivante(); }; -app. et( +app.et( '/example/d', [cb0, cb1], (req, res, next) => { - console. og('la réponse sera envoyée par la fonction suivante . .'); + console.og('la réponse sera envoyée par la fonction suivante . .'); next(); }, (req, res) => { - res. end('Bonjour de D!'); + res.end('Bonjour de D!'); } ); ``` @@ -360,12 +360,12 @@ app .get((req, res) => { end('Obtenir un livre aléatoire'); }) - . ost((req, res) => { + .ost((req, res) => { res.send('Ajouter un livre'); }) - . ut((req, res) => { + .ut((req, res) => { res.send('Mettre à jour le livre'); -}); + }); ``` ## Routeur diff --git a/src/content/docs/fr/4x/guide/using-middleware.mdx b/src/content/docs/fr/4x/guide/using-middleware.mdx index 36277e0b0c..3cb37d1ab5 100644 --- a/src/content/docs/fr/4x/guide/using-middleware.mdx +++ b/src/content/docs/fr/4x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express est un framework web de routage et de middleware qui possède des fonctionnalités minimales : Une application Express est essentiellement une série d'appels de fonctions de middleware. -Les fonctions *Middleware* sont des fonctions qui ont accès à l'objet [request object](/en/5x/api#req) (`req`), l'objet [réponse](/en/5x/api#res) (`res`), et la prochaine fonction du middleware dans le cycle de réponse de l'application. La prochaine fonction du middleware est généralement dénotée par une variable nommée `next`. +Les fonctions _Middleware_ sont des fonctions qui ont accès à l'objet [request object](/en/5x/api#req) (`req`), l'objet [réponse](/en/5x/api#res) (`res`), et la prochaine fonction du middleware dans le cycle de réponse de l'application. La prochaine fonction du middleware est généralement dénotée par une variable nommée `next`. Les fonctions Middleware peuvent effectuer les tâches suivantes : -* Exécuter n'importe quel code. -* Effectuez des modifications à la requête et aux objets de réponse. -* Termine le cycle de réponse de la requête. -* Appeler la prochaine fonction du middleware dans la pile. +- Exécuter n'importe quel code. +- Effectuez des modifications à la requête et aux objets de réponse. +- Termine le cycle de réponse de la requête. +- Appeler la prochaine fonction du middleware dans la pile. Si la fonction middleware actuelle ne met pas fin au cycle de réponse de requête, elle doit appeler `next()` pour passer le contrôle à la prochaine fonction du middleware. Sinon, la demande sera laissée en suspens. Une application Express peut utiliser les types de middleware suivants : -* (#middleware.application) -* [middleware au niveau du routeur] (#middleware.router) -* (#middleware.error-handling) -* (#middleware.built-in) -* [middleware de tierce partie](#middleware.third-party) +- (#middleware.application) +- [middleware au niveau du routeur] (#middleware.router) +- (#middleware.error-handling) +- (#middleware.built-in) +- [middleware de tierce partie](#middleware.third-party) Vous pouvez charger le middleware au niveau de l'application et du routeur avec un chemin de montage optionnel. Vous pouvez également charger une série de fonctions middleware ensemble, ce qui crée une sous-pile du système middleware à un point de montage. @@ -140,17 +140,17 @@ Cet exemple montre un tableau avec une sous-pile middleware qui gère les requê ```js function logOriginalUrl(req, res, next) { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); } function logMethod(req, res, next) { - console.log('Type de requête:', req. ethod); + console.log('Type de requête:', req.ethod); next(); } const logStuff = [logOriginalUrl, logMethod]; -app. et('/user/:id', logStuff, (req, res, next) => { +app.et('/user/:id', logStuff, (req, res, next) => { res.send('User Info'); }); ``` @@ -246,7 +246,7 @@ routeur. et('/user/:id', (req, res) => { -La gestion d'erreurs du middleware prend toujours *four* arguments. Vous devez fournir quatre arguments à +La gestion d'erreurs du middleware prend toujours _four_ arguments. Vous devez fournir quatre arguments à l'identifier comme une fonction de gestion des erreurs du middleware. Même si vous n'avez pas besoin d'utiliser l'objet `next` , vous devez le spécifier pour maintenir la signature. Sinon, l'objet `next` sera interprété comme un middleware normal et ne gérera pas les erreurs. @@ -271,9 +271,9 @@ qui étaient précédemment incluses avec Express sont maintenant dans des modul Express a les fonctions internes suivantes : -* [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. -* [express.json](/en/5x/api#express.json) analyse les requêtes entrantes avec des charges utiles JSON. **NOTE : Disponible avec Express 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) analyse les requêtes entrantes avec des charges utiles encodées en URL. **NOTE : Disponible avec Express 4.16.0+** +- [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. +- [express.json](/en/5x/api#express.json) analyse les requêtes entrantes avec des charges utiles JSON. **NOTE : Disponible avec Express 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) analyse les requêtes entrantes avec des charges utiles encodées en URL. **NOTE : Disponible avec Express 4.16.0+** ## middleware de tierce partie diff --git a/src/content/docs/fr/4x/guide/using-template-engines.mdx b/src/content/docs/fr/4x/guide/using-template-engines.mdx index 581a2b0cca..af25252ab8 100644 --- a/src/content/docs/fr/4x/guide/using-template-engines.mdx +++ b/src/content/docs/fr/4x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Découvrez comment intégrer et utiliser des moteurs de gabarits te import Alert from '@components/primitives/Alert/Alert.astro'; -Un *moteur de modèle* vous permet d'utiliser des fichiers de modèles statiques dans votre application. Lors de l'exécution, le moteur de gabarit remplace les variables +Un _moteur de modèle_ vous permet d'utiliser des fichiers de modèles statiques dans votre application. Lors de l'exécution, le moteur de gabarit remplace les variables dans un fichier de gabarit par des valeurs réelles, et transforme le modèle en un fichier HTML envoyé au client. Cette approche facilite la conception d'une page HTML. @@ -13,9 +13,9 @@ Le [générateur d'application Express](/en/starter/generator) utilise [Pug](htt Pour afficher les fichiers de gabarit, définissez les [propriétés de réglage de l'application](/en/4x/api#app.set), dans le `app.js` par défaut créé par le générateur: -* `views`, le répertoire où se trouvent les fichiers de modèle. Ex. : `app.set('vues', './views')`. +- `views`, le répertoire où se trouvent les fichiers de modèle. Ex. : `app.set('vues', './views')`. Par défaut, le répertoire `views` se trouve à la racine de l'application. -* `voir le moteur`, le moteur de gabarit à utiliser. Par exemple, pour utiliser le moteur de gabarit Pug : `app.set('moteur de vue', 'pug')`. +- `voir le moteur`, le moteur de gabarit à utiliser. Par exemple, pour utiliser le moteur de gabarit Pug : `app.set('moteur de vue', 'pug')`. Ensuite, installez le paquet npm correspondant au moteur de gabarits ; par exemple pour installer Pug: diff --git a/src/content/docs/fr/4x/guide/writing-middleware.mdx b/src/content/docs/fr/4x/guide/writing-middleware.mdx index 06237ba1ee..08145c2141 100644 --- a/src/content/docs/fr/4x/guide/writing-middleware.mdx +++ b/src/content/docs/fr/4x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Apprenez à écrire des fonctions personnalisées de middleware pou import Alert from '@components/primitives/Alert/Alert.astro'; -Les fonctions *Middleware* sont des fonctions qui ont accès à l'objet [request object](/en/5x/api#req) (`req`), l'objet [réponse](/en/5x/api#res) (`res`), et la fonction `next` dans le cycle de réponse de l'application. La fonction `next` est une fonction dans le routeur Express qui, lorsqu'elle est appelée, exécute le middleware qui succède au middleware actuel. +Les fonctions _Middleware_ sont des fonctions qui ont accès à l'objet [request object](/en/5x/api#req) (`req`), l'objet [réponse](/en/5x/api#res) (`res`), et la fonction `next` dans le cycle de réponse de l'application. La fonction `next` est une fonction dans le routeur Express qui, lorsqu'elle est appelée, exécute le middleware qui succède au middleware actuel. Les fonctions Middleware peuvent effectuer les tâches suivantes : -* Exécuter n'importe quel code. -* Effectuez des modifications à la requête et aux objets de réponse. -* Termine le cycle de réponse de la requête. -* Appelez le prochain middleware dans la pile. +- Exécuter n'importe quel code. +- Effectuez des modifications à la requête et aux objets de réponse. +- Termine le cycle de réponse de la requête. +- Appelez le prochain middleware dans la pile. Si la fonction middleware actuelle ne met pas fin au cycle de réponse de requête, elle doit appeler `next()` pour passer le contrôle à la prochaine fonction du middleware. Sinon, la demande sera laissée en suspens. @@ -40,8 +40,8 @@ La figure suivante montre les éléments d'un appel de fonction middleware :
    - L'argument HTTP réponse à la fonction middleware appelée "res" par convention - . + L'argument HTTP réponse à la fonction middleware appelée "res" par + convention .
    HTTP demande argument à la fonction middleware appelée "req" par convention.
    @@ -100,7 +100,7 @@ const express = require('express'); const app = express(); const myLogger = function (req, res, next) { - console. og('LOGGED'); + console.og('LOGGED'); next(); }; @@ -140,16 +140,16 @@ const express = require('express'); const app = express(); const requestTime = function (req, res, next) { - req. equestTime = Date.now(); + req.equestTime = Date.now(); next(); }; app.use(requestTime); -app. et('/', (req, res) => { +app.et('/', (req, res) => { let responseText = 'Bonjour le monde!
    '; responseText += `Demandé à: ${req.requestTime}`; - res. end(responseText); + res.end(responseText); }); app.listen(3000); diff --git a/src/content/docs/fr/4x/starter/basic-routing.mdx b/src/content/docs/fr/4x/starter/basic-routing.mdx index 1259c9d112..cc7681f5ea 100644 --- a/src/content/docs/fr/4x/starter/basic-routing.mdx +++ b/src/content/docs/fr/4x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Apprenez les fondamentaux du routage dans les applications Express. import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* désigne la façon dont une application répond à une requête client à un point de terminaison particulier, qui est une URI (ou un chemin) et une méthode spécifique de requête HTTP (GET, POST, etc.). +_Routing_ désigne la façon dont une application répond à une requête client à un point de terminaison particulier, qui est une URI (ou un chemin) et une méthode spécifique de requête HTTP (GET, POST, etc.). Chaque route peut avoir une ou plusieurs fonctions de gestionnaire, qui sont exécutées lorsque la route est correspondante. @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); Où : -* `app` est une instance de `express`. -* `METHOD` est une [méthode de requête HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), en minuscule. -* `PATH` est un chemin sur le serveur. -* `HANDLER` est la fonction exécutée lorsque la route est correspondante. +- `app` est une instance de `express`. +- `METHOD` est une [méthode de requête HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), en minuscule. +- `PATH` est un chemin sur le serveur. +- `HANDLER` est la fonction exécutée lorsque la route est correspondante. diff --git a/src/content/docs/fr/4x/starter/examples.mdx b/src/content/docs/fr/4x/starter/examples.mdx index 3ab740ea07..8d390b2ce9 100644 --- a/src/content/docs/fr/4x/starter/examples.mdx +++ b/src/content/docs/fr/4x/starter/examples.mdx @@ -5,41 +5,41 @@ description: Explorez une collection d'exemples d'applications Express.js couvra import Alert from '@components/primitives/Alert/Alert.astro'; -* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Authentification avec login et mot de passe -* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - négociation de contenu HTTP -* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Working with cookie-based sessions -* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Working with cookies -* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transfert de fichiers vers le client -* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Travailler avec un modèle JavaScript embarqué (ejs) -* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Création des pages d'erreur -* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Travailler avec un middleware d'erreur -* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Gestionnaire de requêtes simple -* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown comme moteur de gabarit -* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Travailler avec plusieurs routeurs Express -* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - Contrôleurs de style MVC -* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Suivi de l'activité de l'utilisateur en ligne avec les paquets `online` et `redis` -* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Travailler avec les paramètres de la route -* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Opérations HTTP multiples sur la même ressource -* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organiser des routes à l'aide d'une carte -* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Travailler avec le middleware de route -* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organiser des routes par ressource -* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Search API -* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - Sessions utilisateur -* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Servir des fichiers statiques -* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Working with virtual hosts -* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Rendu dynamique des vues -* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Enregistrement des données dans l'objet de requête entre les appels de middleware -* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Service API simple +- [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Authentification avec login et mot de passe +- [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - négociation de contenu HTTP +- [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Working with cookie-based sessions +- [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Working with cookies +- [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transfert de fichiers vers le client +- [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Travailler avec un modèle JavaScript embarqué (ejs) +- [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Création des pages d'erreur +- [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Travailler avec un middleware d'erreur +- [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Gestionnaire de requêtes simple +- [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown comme moteur de gabarit +- [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Travailler avec plusieurs routeurs Express +- [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - Contrôleurs de style MVC +- [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Suivi de l'activité de l'utilisateur en ligne avec les paquets `online` et `redis` +- [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Travailler avec les paramètres de la route +- [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Opérations HTTP multiples sur la même ressource +- [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organiser des routes à l'aide d'une carte +- [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Travailler avec le middleware de route +- [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organiser des routes par ressource +- [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Search API +- [session](https://github.com/expressjs/express/tree/4.x/examples/session) - Sessions utilisateur +- [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Servir des fichiers statiques +- [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Working with virtual hosts +- [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Rendu dynamique des vues +- [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Enregistrement des données dans l'objet de requête entre les appels de middleware +- [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Service API simple ## Exemples supplémentaires Ce sont quelques exemples supplémentaires avec des intégrations plus étendues. - Cette information se réfère à des sites tiers, des produits ou des modules tiers qui ne sont pas maintenus par l'équipe - Expressjs. La liste ci-dessous ne constitue pas une approbation ou une recommandation de l'équipe du projet - Expressjs. + Cette information se réfère à des sites tiers, des produits ou des modules tiers qui ne sont pas + maintenus par l'équipe Expressjs. La liste ci-dessous ne constitue pas une approbation ou une + recommandation de l'équipe du projet Expressjs. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Application Fullstack avec Express et Next.js en utilisant [Prisma](https://www.npmjs.com/package/prisma) en tant qu'ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API avec Express in TypeScript en utilisant [Prisma](https://www.npmjs.com/package/prisma) en tant qu'ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Application Fullstack avec Express et Next.js en utilisant [Prisma](https://www.npmjs.com/package/prisma) en tant qu'ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API avec Express in TypeScript en utilisant [Prisma](https://www.npmjs.com/package/prisma) en tant qu'ORM diff --git a/src/content/docs/fr/4x/starter/generator.mdx b/src/content/docs/fr/4x/starter/generator.mdx index fdfd9b4883..697016481d 100644 --- a/src/content/docs/fr/4x/starter/generator.mdx +++ b/src/content/docs/fr/4x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force sur un répertoire non vide ``` -Par exemple, ce qui suit crée une application Express nommée *myapp*. L'application sera créée dans un dossier nommé *myapp* dans le répertoire de travail actuel et le moteur de vue sera réglé sur Pug: +Par exemple, ce qui suit crée une application Express nommée _myapp_. L'application sera créée dans un dossier nommé _myapp_ dans le répertoire de travail actuel et le moteur de vue sera réglé sur Pug: ```bash $ express --view=pug myapp diff --git a/src/content/docs/fr/4x/starter/hello-world.mdx b/src/content/docs/fr/4x/starter/hello-world.mdx index 8e38e29de6..1c7704047e 100644 --- a/src/content/docs/fr/4x/starter/hello-world.mdx +++ b/src/content/docs/fr/4x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Intégré ci-dessous est essentiellement l'application Express la plus simple que vous puissiez créer. C'est une seule application de fichier -— *pas* ce que vous obtiendrez si vous utilisez le [générateur Express](/en/starter/generator), que +— _pas_ ce que vous obtiendrez si vous utilisez le [générateur Express](/en/starter/generator), que crée l'échafaudage pour une application complète avec de nombreux fichiers JavaScript, des modèles Jade, et des sous-répertoires à diverses fins. @@ -20,7 +20,7 @@ const app = express(); const port = 3000; app.get('/', (req, res) => { - res. end('Hello World!'); + res.end('Hello World!'); }); app.listen(port, () => { @@ -29,7 +29,7 @@ app.listen(port, () => { ``` Cette application démarre un serveur et écoute le port 3000 pour les connexions. L'application répond avec "Hello World!" pour les demandes -à l'URL racine (`/`) ou *route*. Pour tous les autres chemins, il répondra avec un **404 Not Found**. +à l'URL racine (`/`) ou _route_. Pour tous les autres chemins, il répondra avec un **404 Not Found**. ## Exécution locale diff --git a/src/content/docs/fr/5x/guide/behind-proxies.mdx b/src/content/docs/fr/5x/guide/behind-proxies.mdx index 1eabee667b..aa17a36f63 100644 --- a/src/content/docs/fr/5x/guide/behind-proxies.mdx +++ b/src/content/docs/fr/5x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ Lorsque vous définissez sur `true`, il est important de s'assurer que le dernie Une adresse IP, un sous-réseau ou un tableau d'adresses IP et de sous-réseaux à confier comme étant un proxy inverse. La liste suivante montre les noms de sous-réseaux pré-configurés : -* loopback - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` Vous pouvez définir les adresses IP de l'une des façons suivantes : @@ -86,16 +86,18 @@ Activer `trust proxy` aura l'impact suivant :
    • - La valeur de [req.hostname](/en/api#req.hostname) est dérivée de la valeur définie dans l'en-tête - `X-Forwarded-Host`, qui peut être définie par le client ou par le proxy. + La valeur de [req.hostname](/en/api#req.hostname) est dérivée de la valeur définie dans + l'en-tête `X-Forwarded-Host`, qui peut être définie par le client ou par le proxy.
    • - `X-Forwarded-Proto` peut être défini par le proxy inverse pour dire à l'application si c'est `https` ou - `http` ou même un nom invalide. Cette valeur est reflétée par [req.protocol](/en/api#req.protocol). + `X-Forwarded-Proto` peut être défini par le proxy inverse pour dire à l'application si c'est + `https` ou `http` ou même un nom invalide. Cette valeur est reflétée par + [req.protocol](/en/api#req.protocol).
    • - Les valeurs [req.ip](/en/api#req.ip) et [req.ips](/en/api#req.ips) sont remplies en fonction de l'adresse du socket - et de l'en-tête `X-Forwarded-For`, à partir de la première adresse non fiable. + Les valeurs [req.ip](/en/api#req.ip) et [req.ips](/en/api#req.ips) sont remplies en fonction de + l'adresse du socket et de l'en-tête `X-Forwarded-For`, à partir de la première adresse non + fiable.
    diff --git a/src/content/docs/fr/5x/guide/error-handling.mdx b/src/content/docs/fr/5x/guide/error-handling.mdx index 1ef9f11421..0bcd847565 100644 --- a/src/content/docs/fr/5x/guide/error-handling.mdx +++ b/src/content/docs/fr/5x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Comprenez comment Express.js gère les erreurs dans le code synchro import Alert from '@components/primitives/Alert/Alert.astro'; -*Error Handling* fait référence à la façon dont Express attrape et traite les erreurs que +_Error Handling_ fait référence à la façon dont Express attrape et traite les erreurs que se produisent de manière synchronisée et asynchrone. Express comes with a default error handler so you don't need to write your own to get started. @@ -30,11 +30,11 @@ catch and process them. Par exemple : ```js app.get('/', (req, res, next) => { - fs. eadFile('/file-does-not-exist', (err, data) => { + fs.eadFile('/file-does-not-exist', (err, data) => { if (err) { next(err); // Passez des erreurs à Express. } else { - res. end(data); + res.end(data); } }); }); @@ -103,10 +103,10 @@ qui renvoient des promesses. Par exemple : ```js app.get('/', (req, res, next) => { Promise.resolve() - . hen(() => { + .hen(() => { throw new Error('BROKEN'); }) - . atch(next); // Les erreurs seront passées à Express. + .atch(next); // Les erreurs seront passées à Express. }); ``` @@ -161,12 +161,12 @@ Définissez la variable d'environnement `NODE_ENV` à `production`, pour exécut Lorsqu'une erreur est écrite, les informations suivantes sont ajoutées à la réponse : -* Le `res.statusCode` est défini à partir de `err.status` (ou `err.statusCode`). Si +- Le `res.statusCode` est défini à partir de `err.status` (ou `err.statusCode`). Si cette valeur est en dehors de la plage 4xx ou 5xx, elle sera définie à 500. -* Le `res.statusMessage` est défini selon le code de statut. -* Le corps sera le HTML du message de code de statut lorsque l'environnement de production +- Le `res.statusMessage` est défini selon le code de statut. +- Le corps sera le HTML du message de code de statut lorsque l'environnement de production , sinon sera `err.stack`. -* N'importe quel en-tête spécifié dans un objet `err.headers`. +- N'importe quel en-tête spécifié dans un objet `err.headers`. Si vous appelez `next()` avec une erreur après avoir commencé à écrire la réponse (par exemple, si vous rencontrez une erreur lors du streaming de la réponse @@ -212,12 +212,12 @@ const bodyParser = require('body-parser'); const methodOverride = require('method-override'); app.use( - bodyParser. rlencoded({ + bodyParser.rlencoded({ étendu: true, }) ); app.use(bodyParser.json()); -app. se(methodOverride()); +app.se(methodOverride()); app.use((err, req, res, next) => { // logique }); @@ -234,12 +234,12 @@ pour les requêtes faites en utilisant `XHR` et ceux sans : const bodyParser = require('body-parser'); const methodOverride = require('method-override'); -application. se( +application.se( bodyParser.urlencoded({ étendu: true, }) ); -app. se(bodyParser.json()); +app.se(bodyParser.json()); app.use(methodOverride()); app.use(logErrors); app.use(clientErrorHandler); @@ -258,12 +258,12 @@ function logErrors(err, req, res, next) { Aussi dans cet exemple, `clientErrorHandler` est défini comme suit ; dans ce cas, l'erreur est explicitement passée au suivant. -Notez que lorsque *not* appelez "next" dans une fonction de gestion des erreurs, vous êtes responsable de l'écriture (et de la fin) de la réponse. Sinon, ces demandes seront « bloquées » et ne seront pas admissibles au ramassage des déchets. +Notez que lorsque _not_ appelez "next" dans une fonction de gestion des erreurs, vous êtes responsable de l'écriture (et de la fin) de la réponse. Sinon, ces demandes seront « bloquées » et ne seront pas admissibles au ramassage des déchets. ```js function clientErrorHandler(err, req, res, next) { if (req.xhr) { - res.status(500). end({ error: 'Quelque chose a échoué!' }); + res.status(500).end({ error: 'Quelque chose a échoué!' }); } else { next(err); } diff --git a/src/content/docs/fr/5x/guide/routing.mdx b/src/content/docs/fr/5x/guide/routing.mdx index 65e3d690e4..3c009b7b16 100644 --- a/src/content/docs/fr/5x/guide/routing.mdx +++ b/src/content/docs/fr/5x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Apprenez à définir et utiliser des routes dans les applications E import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* indique comment les terminaux (URIs) d'une application répondent aux requêtes du client. +_Routing_ indique comment les terminaux (URIs) d'une application répondent aux requêtes du client. Pour une introduction au routage, voir [Routage de base](/en/starter/basic-routing). Vous définissez le routage à l'aide des méthodes de l'objet Express `app` qui correspondent aux méthodes HTTP; @@ -52,7 +52,7 @@ app. ost('/', (req, res) => { Express supporte les méthodes qui correspondent à toutes les méthodes de requête HTTP : `get`, `post`, et ainsi de suite. Pour une liste complète, voir [app.METHOD](/en/5x/api#app.METHOD). -Il y a une méthode de routage spéciale, `app.all()`, utilisée pour charger les fonctions du middleware à un chemin pour *toutes* les méthodes de requête HTTP. Par exemple, le gestionnaire suivant est exécuté pour les requêtes vers la route `"/secret"` si vous utilisez `GET`, `POST`, `PUT`, `DELETE`, ou toute autre méthode de requête HTTP supportée dans le module [http](https://nodejs.org/api/http.html#http_http_methods). +Il y a une méthode de routage spéciale, `app.all()`, utilisée pour charger les fonctions du middleware à un chemin pour _toutes_ les méthodes de requête HTTP. Par exemple, le gestionnaire suivant est exécuté pour les requêtes vers la route `"/secret"` si vous utilisez `GET`, `POST`, `PUT`, `DELETE`, ou toute autre méthode de requête HTTP supportée dans le module [http](https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { Dans cet exemple : -* `GET /user/5` → géré par la première route → envoie "Utilisateur 5" -* `GET /user/0` → première route appelle `next('route')`, passe à la prochaine route correspondant à `/user/:id` +- `GET /user/5` → géré par la première route → envoie "Utilisateur 5" +- `GET /user/0` → première route appelle `next('route')`, passe à la prochaine route correspondant à `/user/:id` Les gestionnaires de routes peuvent être sous la forme d'une fonction, d'un tableau de fonctions, ou de combinaisons des deux, comme indiqué dans les exemples suivants. @@ -276,7 +276,7 @@ Plus d'une fonction de rappel peut gérer une route (assurez-vous de spécifier app.get( '/example/b', (req, res, next) => { - console. og('la réponse sera envoyée par la fonction suivante . .'); + console.og('la réponse sera envoyée par la fonction suivante . .'); next(); }, (req, res) => { @@ -289,12 +289,12 @@ Un tableau de fonctions de rappel peut gérer une route. Par exemple : ```js const cb0 = function (req, res, suivant) { - console. og('CB0'); + console.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; @@ -309,24 +309,24 @@ Une combinaison de fonctions indépendantes et de tableaux de fonctions peut gé ```js const cb0 = function (req, res, suivant) { - console. og('CB0'); + console.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); suivante(); }; -app. et( +app.et( '/example/d', [cb0, cb1], (req, res, next) => { - console. og('la réponse sera envoyée par la fonction suivante . .'); + console.og('la réponse sera envoyée par la fonction suivante . .'); next(); }, (req, res) => { - res. end('Bonjour de D!'); + res.end('Bonjour de D!'); } ); ``` @@ -360,12 +360,12 @@ app .get((req, res) => { end('Obtenir un livre aléatoire'); }) - . ost((req, res) => { + .ost((req, res) => { res.send('Ajouter un livre'); }) - . ut((req, res) => { + .ut((req, res) => { res.send('Mettre à jour le livre'); -}); + }); ``` ## Routeur diff --git a/src/content/docs/fr/5x/guide/using-middleware.mdx b/src/content/docs/fr/5x/guide/using-middleware.mdx index 36277e0b0c..3cb37d1ab5 100644 --- a/src/content/docs/fr/5x/guide/using-middleware.mdx +++ b/src/content/docs/fr/5x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express est un framework web de routage et de middleware qui possède des fonctionnalités minimales : Une application Express est essentiellement une série d'appels de fonctions de middleware. -Les fonctions *Middleware* sont des fonctions qui ont accès à l'objet [request object](/en/5x/api#req) (`req`), l'objet [réponse](/en/5x/api#res) (`res`), et la prochaine fonction du middleware dans le cycle de réponse de l'application. La prochaine fonction du middleware est généralement dénotée par une variable nommée `next`. +Les fonctions _Middleware_ sont des fonctions qui ont accès à l'objet [request object](/en/5x/api#req) (`req`), l'objet [réponse](/en/5x/api#res) (`res`), et la prochaine fonction du middleware dans le cycle de réponse de l'application. La prochaine fonction du middleware est généralement dénotée par une variable nommée `next`. Les fonctions Middleware peuvent effectuer les tâches suivantes : -* Exécuter n'importe quel code. -* Effectuez des modifications à la requête et aux objets de réponse. -* Termine le cycle de réponse de la requête. -* Appeler la prochaine fonction du middleware dans la pile. +- Exécuter n'importe quel code. +- Effectuez des modifications à la requête et aux objets de réponse. +- Termine le cycle de réponse de la requête. +- Appeler la prochaine fonction du middleware dans la pile. Si la fonction middleware actuelle ne met pas fin au cycle de réponse de requête, elle doit appeler `next()` pour passer le contrôle à la prochaine fonction du middleware. Sinon, la demande sera laissée en suspens. Une application Express peut utiliser les types de middleware suivants : -* (#middleware.application) -* [middleware au niveau du routeur] (#middleware.router) -* (#middleware.error-handling) -* (#middleware.built-in) -* [middleware de tierce partie](#middleware.third-party) +- (#middleware.application) +- [middleware au niveau du routeur] (#middleware.router) +- (#middleware.error-handling) +- (#middleware.built-in) +- [middleware de tierce partie](#middleware.third-party) Vous pouvez charger le middleware au niveau de l'application et du routeur avec un chemin de montage optionnel. Vous pouvez également charger une série de fonctions middleware ensemble, ce qui crée une sous-pile du système middleware à un point de montage. @@ -140,17 +140,17 @@ Cet exemple montre un tableau avec une sous-pile middleware qui gère les requê ```js function logOriginalUrl(req, res, next) { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); } function logMethod(req, res, next) { - console.log('Type de requête:', req. ethod); + console.log('Type de requête:', req.ethod); next(); } const logStuff = [logOriginalUrl, logMethod]; -app. et('/user/:id', logStuff, (req, res, next) => { +app.et('/user/:id', logStuff, (req, res, next) => { res.send('User Info'); }); ``` @@ -246,7 +246,7 @@ routeur. et('/user/:id', (req, res) => { -La gestion d'erreurs du middleware prend toujours *four* arguments. Vous devez fournir quatre arguments à +La gestion d'erreurs du middleware prend toujours _four_ arguments. Vous devez fournir quatre arguments à l'identifier comme une fonction de gestion des erreurs du middleware. Même si vous n'avez pas besoin d'utiliser l'objet `next` , vous devez le spécifier pour maintenir la signature. Sinon, l'objet `next` sera interprété comme un middleware normal et ne gérera pas les erreurs. @@ -271,9 +271,9 @@ qui étaient précédemment incluses avec Express sont maintenant dans des modul Express a les fonctions internes suivantes : -* [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. -* [express.json](/en/5x/api#express.json) analyse les requêtes entrantes avec des charges utiles JSON. **NOTE : Disponible avec Express 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) analyse les requêtes entrantes avec des charges utiles encodées en URL. **NOTE : Disponible avec Express 4.16.0+** +- [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. +- [express.json](/en/5x/api#express.json) analyse les requêtes entrantes avec des charges utiles JSON. **NOTE : Disponible avec Express 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) analyse les requêtes entrantes avec des charges utiles encodées en URL. **NOTE : Disponible avec Express 4.16.0+** ## middleware de tierce partie diff --git a/src/content/docs/fr/5x/guide/using-template-engines.mdx b/src/content/docs/fr/5x/guide/using-template-engines.mdx index 581a2b0cca..af25252ab8 100644 --- a/src/content/docs/fr/5x/guide/using-template-engines.mdx +++ b/src/content/docs/fr/5x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Découvrez comment intégrer et utiliser des moteurs de gabarits te import Alert from '@components/primitives/Alert/Alert.astro'; -Un *moteur de modèle* vous permet d'utiliser des fichiers de modèles statiques dans votre application. Lors de l'exécution, le moteur de gabarit remplace les variables +Un _moteur de modèle_ vous permet d'utiliser des fichiers de modèles statiques dans votre application. Lors de l'exécution, le moteur de gabarit remplace les variables dans un fichier de gabarit par des valeurs réelles, et transforme le modèle en un fichier HTML envoyé au client. Cette approche facilite la conception d'une page HTML. @@ -13,9 +13,9 @@ Le [générateur d'application Express](/en/starter/generator) utilise [Pug](htt Pour afficher les fichiers de gabarit, définissez les [propriétés de réglage de l'application](/en/4x/api#app.set), dans le `app.js` par défaut créé par le générateur: -* `views`, le répertoire où se trouvent les fichiers de modèle. Ex. : `app.set('vues', './views')`. +- `views`, le répertoire où se trouvent les fichiers de modèle. Ex. : `app.set('vues', './views')`. Par défaut, le répertoire `views` se trouve à la racine de l'application. -* `voir le moteur`, le moteur de gabarit à utiliser. Par exemple, pour utiliser le moteur de gabarit Pug : `app.set('moteur de vue', 'pug')`. +- `voir le moteur`, le moteur de gabarit à utiliser. Par exemple, pour utiliser le moteur de gabarit Pug : `app.set('moteur de vue', 'pug')`. Ensuite, installez le paquet npm correspondant au moteur de gabarits ; par exemple pour installer Pug: diff --git a/src/content/docs/fr/5x/guide/writing-middleware.mdx b/src/content/docs/fr/5x/guide/writing-middleware.mdx index 4f2f2062a1..4ca68601a4 100644 --- a/src/content/docs/fr/5x/guide/writing-middleware.mdx +++ b/src/content/docs/fr/5x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Apprenez à écrire des fonctions personnalisées de middleware pou import Alert from '@components/primitives/Alert/Alert.astro'; -Les fonctions *Middleware* sont des fonctions qui ont accès à l'objet [request object](/en/5x/api#req) (`req`), l'objet [réponse](/en/5x/api#res) (`res`), et la fonction `next` dans le cycle de réponse de l'application. La fonction `next` est une fonction dans le routeur Express qui, lorsqu'elle est appelée, exécute le middleware qui succède au middleware actuel. +Les fonctions _Middleware_ sont des fonctions qui ont accès à l'objet [request object](/en/5x/api#req) (`req`), l'objet [réponse](/en/5x/api#res) (`res`), et la fonction `next` dans le cycle de réponse de l'application. La fonction `next` est une fonction dans le routeur Express qui, lorsqu'elle est appelée, exécute le middleware qui succède au middleware actuel. Les fonctions Middleware peuvent effectuer les tâches suivantes : -* Exécuter n'importe quel code. -* Effectuez des modifications à la requête et aux objets de réponse. -* Termine le cycle de réponse de la requête. -* Appelez le prochain middleware dans la pile. +- Exécuter n'importe quel code. +- Effectuez des modifications à la requête et aux objets de réponse. +- Termine le cycle de réponse de la requête. +- Appelez le prochain middleware dans la pile. Si la fonction middleware actuelle ne met pas fin au cycle de réponse de requête, elle doit appeler `next()` pour passer le contrôle à la prochaine fonction du middleware. Sinon, la demande sera laissée en suspens. @@ -70,7 +70,7 @@ const express = require('express'); const app = express(); const myLogger = function (req, res, next) { - console. og('LOGGED'); + console.og('LOGGED'); next(); }; @@ -110,16 +110,16 @@ const express = require('express'); const app = express(); const requestTime = function (req, res, next) { - req. equestTime = Date.now(); + req.equestTime = Date.now(); next(); }; app.use(requestTime); -app. et('/', (req, res) => { +app.et('/', (req, res) => { let responseText = 'Bonjour le monde!
    '; responseText += `Demandé à: ${req.requestTime}`; - res. end(responseText); + res.end(responseText); }); app.listen(3000); diff --git a/src/content/docs/fr/5x/starter/basic-routing.mdx b/src/content/docs/fr/5x/starter/basic-routing.mdx index 1259c9d112..cc7681f5ea 100644 --- a/src/content/docs/fr/5x/starter/basic-routing.mdx +++ b/src/content/docs/fr/5x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Apprenez les fondamentaux du routage dans les applications Express. import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* désigne la façon dont une application répond à une requête client à un point de terminaison particulier, qui est une URI (ou un chemin) et une méthode spécifique de requête HTTP (GET, POST, etc.). +_Routing_ désigne la façon dont une application répond à une requête client à un point de terminaison particulier, qui est une URI (ou un chemin) et une méthode spécifique de requête HTTP (GET, POST, etc.). Chaque route peut avoir une ou plusieurs fonctions de gestionnaire, qui sont exécutées lorsque la route est correspondante. @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); Où : -* `app` est une instance de `express`. -* `METHOD` est une [méthode de requête HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), en minuscule. -* `PATH` est un chemin sur le serveur. -* `HANDLER` est la fonction exécutée lorsque la route est correspondante. +- `app` est une instance de `express`. +- `METHOD` est une [méthode de requête HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), en minuscule. +- `PATH` est un chemin sur le serveur. +- `HANDLER` est la fonction exécutée lorsque la route est correspondante. diff --git a/src/content/docs/fr/5x/starter/examples.mdx b/src/content/docs/fr/5x/starter/examples.mdx index 674e561a00..a0833d9859 100644 --- a/src/content/docs/fr/5x/starter/examples.mdx +++ b/src/content/docs/fr/5x/starter/examples.mdx @@ -7,31 +7,31 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Cette page contient la liste des exemples utilisant Express. -* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Authentification avec login et mot de passe -* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - négociation de contenu HTTP -* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Working with cookie-based sessions -* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Working with cookies -* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transfert de fichiers vers le client -* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Travailler avec un modèle JavaScript embarqué (ejs) -* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Création des pages d'erreur -* [error](https://github.com/expressjs/express/tree/master/examples/error) - Travailler avec un middleware d'erreur -* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Gestionnaire de requêtes simple -* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown comme moteur de gabarit -* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Travailler avec plusieurs routeurs Express -* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - Contrôleurs de style MVC -* [online](https://github.com/expressjs/express/tree/master/examples/online) - Suivi de l'activité de l'utilisateur en ligne avec les paquets `online` et `redis` -* [params](https://github.com/expressjs/express/tree/master/examples/params) - Travailler avec les paramètres de la route -* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Opérations HTTP multiples sur la même ressource -* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organiser des routes à l'aide d'une carte -* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Travailler avec le middleware de route -* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organiser des routes par ressource -* [search](https://github.com/expressjs/express/tree/master/examples/search) - Search API -* [session](https://github.com/expressjs/express/tree/master/examples/session) - Sessions utilisateur -* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Servir des fichiers statiques -* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Working with virtual hosts -* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Rendu dynamique des vues -* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Enregistrement des données dans l'objet de requête entre les appels de middleware -* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Service API simple +- [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Authentification avec login et mot de passe +- [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - négociation de contenu HTTP +- [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Working with cookie-based sessions +- [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Working with cookies +- [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transfert de fichiers vers le client +- [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Travailler avec un modèle JavaScript embarqué (ejs) +- [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Création des pages d'erreur +- [error](https://github.com/expressjs/express/tree/master/examples/error) - Travailler avec un middleware d'erreur +- [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Gestionnaire de requêtes simple +- [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown comme moteur de gabarit +- [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Travailler avec plusieurs routeurs Express +- [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - Contrôleurs de style MVC +- [online](https://github.com/expressjs/express/tree/master/examples/online) - Suivi de l'activité de l'utilisateur en ligne avec les paquets `online` et `redis` +- [params](https://github.com/expressjs/express/tree/master/examples/params) - Travailler avec les paramètres de la route +- [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Opérations HTTP multiples sur la même ressource +- [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organiser des routes à l'aide d'une carte +- [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Travailler avec le middleware de route +- [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organiser des routes par ressource +- [search](https://github.com/expressjs/express/tree/master/examples/search) - Search API +- [session](https://github.com/expressjs/express/tree/master/examples/session) - Sessions utilisateur +- [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Servir des fichiers statiques +- [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Working with virtual hosts +- [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Rendu dynamique des vues +- [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Enregistrement des données dans l'objet de requête entre les appels de middleware +- [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Service API simple ## Exemples supplémentaires @@ -45,5 +45,5 @@ Expressjs. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Application Fullstack avec Express et Next.js en utilisant [Prisma](https://www.npmjs.com/package/prisma) en tant qu'ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API avec Express in TypeScript en utilisant [Prisma](https://www.npmjs.com/package/prisma) en tant qu'ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Application Fullstack avec Express et Next.js en utilisant [Prisma](https://www.npmjs.com/package/prisma) en tant qu'ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API avec Express in TypeScript en utilisant [Prisma](https://www.npmjs.com/package/prisma) en tant qu'ORM diff --git a/src/content/docs/fr/5x/starter/generator.mdx b/src/content/docs/fr/5x/starter/generator.mdx index fdfd9b4883..697016481d 100644 --- a/src/content/docs/fr/5x/starter/generator.mdx +++ b/src/content/docs/fr/5x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force sur un répertoire non vide ``` -Par exemple, ce qui suit crée une application Express nommée *myapp*. L'application sera créée dans un dossier nommé *myapp* dans le répertoire de travail actuel et le moteur de vue sera réglé sur Pug: +Par exemple, ce qui suit crée une application Express nommée _myapp_. L'application sera créée dans un dossier nommé _myapp_ dans le répertoire de travail actuel et le moteur de vue sera réglé sur Pug: ```bash $ express --view=pug myapp diff --git a/src/content/docs/fr/5x/starter/hello-world.mdx b/src/content/docs/fr/5x/starter/hello-world.mdx index 8e38e29de6..1c7704047e 100644 --- a/src/content/docs/fr/5x/starter/hello-world.mdx +++ b/src/content/docs/fr/5x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Intégré ci-dessous est essentiellement l'application Express la plus simple que vous puissiez créer. C'est une seule application de fichier -— *pas* ce que vous obtiendrez si vous utilisez le [générateur Express](/en/starter/generator), que +— _pas_ ce que vous obtiendrez si vous utilisez le [générateur Express](/en/starter/generator), que crée l'échafaudage pour une application complète avec de nombreux fichiers JavaScript, des modèles Jade, et des sous-répertoires à diverses fins. @@ -20,7 +20,7 @@ const app = express(); const port = 3000; app.get('/', (req, res) => { - res. end('Hello World!'); + res.end('Hello World!'); }); app.listen(port, () => { @@ -29,7 +29,7 @@ app.listen(port, () => { ``` Cette application démarre un serveur et écoute le port 3000 pour les connexions. L'application répond avec "Hello World!" pour les demandes -à l'URL racine (`/`) ou *route*. Pour tous les autres chemins, il répondra avec un **404 Not Found**. +à l'URL racine (`/`) ou _route_. Pour tous les autres chemins, il répondra avec un **404 Not Found**. ## Exécution locale diff --git a/src/content/docs/it/4x/guide/behind-proxies.mdx b/src/content/docs/it/4x/guide/behind-proxies.mdx index eeb3cb8160..a31c0ad959 100644 --- a/src/content/docs/it/4x/guide/behind-proxies.mdx +++ b/src/content/docs/it/4x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ Quando si imposta a `true`, è importante assicurarsi che l'ultimo proxy inverso Un indirizzo IP, una sottorete, o un array di indirizzi IP e sottoreti a cui fidarsi come proxy inverso. Il seguente elenco mostra i nomi pre-configurati delle sottorete -* loopback - `127.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` È possibile impostare gli indirizzi IP in uno dei seguenti modi: @@ -86,16 +86,18 @@ Abilitare il `trust proxy` avrà il seguente impatto:
    • - Il valore di [req.hostname](/en/api#req.hostname) è derivato dal valore impostato nell'intestazione - `X-Forwarded-Host`, che può essere impostato dal cliente o dal proxy. + Il valore di [req.hostname](/en/api#req.hostname) è derivato dal valore impostato + nell'intestazione `X-Forwarded-Host`, che può essere impostato dal cliente o dal proxy.
    • - `X-Forwarded-Proto` può essere impostato dal proxy inverso per dire all'app se si tratta di `↓ ` o - `http` o anche di un nome non valido. Questo valore è riflesso da [req.protocol](/en/api#req.protocol). + `X-Forwarded-Proto` può essere impostato dal proxy inverso per dire all'app se si tratta di `↓ ` + o `http` o anche di un nome non valido. Questo valore è riflesso da + [req.protocol](/en/api#req.protocol).
    • - I valori [req.ip](/en/api#req.ip) e [req.ips](/en/api#req.ips) sono popolati in base all'indirizzo del socket - e all'intestazione `X-Forwarded-For`, a partire dal primo indirizzo non fidato. + I valori [req.ip](/en/api#req.ip) e [req.ips](/en/api#req.ips) sono popolati in base + all'indirizzo del socket e all'intestazione `X-Forwarded-For`, a partire dal primo indirizzo non + fidato.
    diff --git a/src/content/docs/it/4x/guide/error-handling.mdx b/src/content/docs/it/4x/guide/error-handling.mdx index affc346d07..3378bd2b75 100644 --- a/src/content/docs/it/4x/guide/error-handling.mdx +++ b/src/content/docs/it/4x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Capire come Express.js gestisce gli errori nel codice sincrono e as import Alert from '@components/primitives/Alert/Alert.astro'; -*Error Handling* si riferisce a come Express cattura ed elabora gli errori +_Error Handling_ si riferisce a come Express cattura ed elabora gli errori che si verificano in modo sincrono e asincrono. Express viene fornito con un gestore di errore predefinito quindi non è necessario scrivere il proprio per iniziare. @@ -30,11 +30,11 @@ catturarli ed elaborarli. Per esempio: ```js app.get('/', (req, res, next) => { - fs. eadFile('/file-does-not-exist', (err, data) => { + fs.eadFile('/file-does-not-exist', (err, data) => { if (err) { next(err); // Passa gli errori a Express. } else { - res. end(dati); + res.end(dati); } }); }); @@ -103,10 +103,10 @@ che restituiscono le promesse. Per esempio: ```js app.get('/', (req, res, next) => { Promise.resolve() - . hen(() => { + .hen(() => { throw new Error('BROKEN'); }) - . atch(next); // Gli errori saranno passati a Express. + .atch(next); // Gli errori saranno passati a Express. }); ``` @@ -120,13 +120,13 @@ catching, riducendo il codice asincrono a qualcosa di banale. Per esempio: ```js app.get('/', [ function (req, res, next) { - fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { - res.locals. ata = dati; + fs.eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals.ata = dati; next(err); }); }, function (req, res) { - res. ocals.data = res.locals.data.split(',')[1]; + res.ocals.data = res.locals.data.split(',')[1]; res.send(res.locals.data); }, ]); @@ -161,12 +161,12 @@ Imposta la variabile d'ambiente `NODE_ENV` su `production`, per eseguire l'appli Quando viene scritto un errore, alla risposta vengono aggiunte le seguenti informazioni: -* Il `res.statusCode` è impostato da `err.status` (o `err.statusCode`). Se +- Il `res.statusCode` è impostato da `err.status` (o `err.statusCode`). Se questo valore è al di fuori dell'intervallo 4xx o 5xx, sarà impostato a 500. -* Il `res.statusMessage` è impostato in base al codice di stato. -* Il corpo sarà l'HTML del messaggio del codice di stato quando in ambiente di produzione +- Il `res.statusMessage` è impostato in base al codice di stato. +- Il corpo sarà l'HTML del messaggio del codice di stato quando in ambiente di produzione , altrimenti sarà `err.stack`. -* Qualsiasi intestazione specificata in un oggetto `err.headers`. +- Qualsiasi intestazione specificata in un oggetto `err.headers`. Se chiami `next()` con un errore dopo aver iniziato a scrivere la risposta (ad esempio, se riscontri un errore durante lo streaming della risposta @@ -212,12 +212,12 @@ const bodyParser = require('body-parser'); const methodOverride = require('method-override'); app.use( - bodyParser. rlencoded({ + bodyParser.rlencoded({ extended: true, }) ); app.use(bodyParser.json()); -app. se(methodOverride()); +app.se(methodOverride()); app.use((err, req, res, next) => { // logic }); @@ -258,12 +258,12 @@ function logErrors(err, req, res, next) { Anche in questo esempio, `clientErrorHandler` è definito come segue; in questo caso, l'errore viene esplicitamente passato a quello successivo. -Nota che quando *non* chiama "next" in una funzione di gestione degli errori, sei responsabile della scrittura (e della fine) della risposta. In caso contrario, tali richieste saranno "appese" e non saranno ammissibili per la raccolta rifiuti. +Nota che quando _non_ chiama "next" in una funzione di gestione degli errori, sei responsabile della scrittura (e della fine) della risposta. In caso contrario, tali richieste saranno "appese" e non saranno ammissibili per la raccolta rifiuti. ```js function clientErrorHandler(err, req, res, next) { if (req.xhr) { - res.status(500). end({ error: 'Something failed!' }); + res.status(500).end({ error: 'Something failed!' }); } else { next(err); } @@ -285,7 +285,7 @@ Se si dispone di un gestore del percorso con molteplici funzioni di callback, è app.get( '/a_route_behind_paywall', (req, res, next) => { - if (!req.user. asPaid) { + if (!req.user.asPaid) { // continue handling this request next('route'); } else { @@ -293,9 +293,9 @@ app.get( } }, (req, res, next) => { - PaidContent. ind((err, doc) => { + PaidContent.ind((err, doc) => { if (err) return next(err); - res. son(doc); + res.son(doc); }); } ); diff --git a/src/content/docs/it/4x/guide/routing.mdx b/src/content/docs/it/4x/guide/routing.mdx index 4a65c235d4..19873bbdf3 100644 --- a/src/content/docs/it/4x/guide/routing.mdx +++ b/src/content/docs/it/4x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Scopri come definire e utilizzare i percorsi nelle applicazioni Exp import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* si riferisce a come gli endpoint di un'applicazione (URI) rispondono alle richieste del client. +_Routing_ si riferisce a come gli endpoint di un'applicazione (URI) rispondono alle richieste del client. Per un'introduzione al routing, vedere [Instradamento di base](/en/starter/basic-routing). Definisci il routing usando metodi dell'oggetto `app` Express che corrispondono ai metodi HTTP; @@ -40,11 +40,11 @@ Il seguente codice è un esempio di percorsi definiti per il `GET` e i metodi `P ```js // GET method route app.get('/', (req, res) => { - res. end('Richiesta GET alla homepage'); + res.end('Richiesta GET alla homepage'); }); // POST metodo percorso -app. ost('/', (req, res) => { +app.ost('/', (req, res) => { res.send('POST request to the homepage'); }); ``` @@ -52,7 +52,7 @@ app. ost('/', (req, res) => { Express supporta metodi che corrispondono a tutti i metodi di richiesta HTTP: `get`, `post`, e così via. Per un elenco completo, vedere [app.METHOD](/en/5x/api#app.METHOD). -C'è un metodo di routing speciale, `app.all()`, utilizzato per caricare le funzioni middleware in un percorso per *tutti* i metodi di richiesta HTTP. Ad esempio, il seguente gestore viene eseguito per le richieste al percorso `"/secret"` se si utilizza `GET`, `POST`, `PUT`, `DELETE`, o qualsiasi altro metodo di richiesta HTTP supportato nel [modulo http](https://nodejs.org/api/http.html#http_http_methods). +C'è un metodo di routing speciale, `app.all()`, utilizzato per caricare le funzioni middleware in un percorso per _tutti_ i metodi di richiesta HTTP. Ad esempio, il seguente gestore viene eseguito per le richieste al percorso `"/secret"` se si utilizza `GET`, `POST`, `PUT`, `DELETE`, o qualsiasi altro metodo di richiesta HTTP supportato nel [modulo http](https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -244,10 +244,10 @@ In Express 4.x, il ca ```js app.get('/user/:id', (req, res, next) => { - if (req.params. d === '0') { + if (req.params.d === '0') { return next('route'); } - res. end(`User ${req.params.id}`); + res.end(`User ${req.params.id}`); }); app.get('/user/:id', (req, res) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { In questo esempio: -* `GET /user/5` → gestito dal primo percorso → invia "User 5" -* `GET /user/0` → prima rotta chiama `next('route')`, saltando al prossimo percorso corrispondente `/user/:id` +- `GET /user/5` → gestito dal primo percorso → invia "User 5" +- `GET /user/0` → prima rotta chiama `next('route')`, saltando al prossimo percorso corrispondente `/user/:id` I gestori del percorso possono essere nella forma di una funzione, una serie di funzioni, o combinazioni di entrambi, come mostrato negli esempi seguenti. @@ -276,11 +276,11 @@ Più di una funzione di callback può gestire un percorso (assicurati di specifi app.get( '/example/b', (req, res, next) => { - console. og('la risposta verrà inviata dalla funzione successiva . .'); + console.og('la risposta verrà inviata dalla funzione successiva . .'); next(); }, (req, res) => { - res. end('Ciao da B!'); + res.end('Ciao da B!'); } ); ``` @@ -289,17 +289,17 @@ Un array di funzioni di callback può gestire un percorso. Per esempio: ```js const cb0 = function (req, res, next) { - console. og('CB0'); + console.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; const cb2 = function (req, res) { - res. end('Ciao da C!'); + res.end('Ciao da C!'); }; app.get('/example/c', [cb0, cb1, cb2]); @@ -309,24 +309,24 @@ Una combinazione di funzioni indipendenti e matrici di funzioni può gestire un ```js const cb0 = function (req, res, next) { - console. og('CB0'); + console.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; -app. et( +app.et( '/example/d', [cb0, cb1], (req, res, next) => { - console. og('la risposta verrà inviata dalla funzione successiva . .'); + console.og('la risposta verrà inviata dalla funzione successiva . .'); next(); }, (req, res) => { - res. end('Ciao da D!'); + res.end('Ciao da D!'); } ); ``` @@ -358,14 +358,14 @@ Ecco un esempio di router incatenati che sono definiti utilizzando `app.route()` app .route('/book') .get((req, res) => { - res. end('Ottieni un libro casuale'); + res.end('Ottieni un libro casuale'); }) - . ost((req, res) => { + .ost((req, res) => { res.send('Add a book'); }) - . ut((req, res) => { + .ut((req, res) => { res.send('Aggiorna il libro'); -}); + }); ``` ## express.Router diff --git a/src/content/docs/it/4x/guide/using-middleware.mdx b/src/content/docs/it/4x/guide/using-middleware.mdx index d076967bee..25d334aeb0 100644 --- a/src/content/docs/it/4x/guide/using-middleware.mdx +++ b/src/content/docs/it/4x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express è un framework web routing e middleware che ha funzionalità minime proprie: Un'applicazione Express è essenzialmente una serie di chiamate di funzioni middleware. -Le funzioni *Middleware* sono funzioni che hanno accesso al [request object](/en/5x/api#req) (`req`), il [response object](/en/5x/api#res) (`res`), e la successiva funzione middleware nel ciclo request-response dell'applicazione. La funzione middleware successiva è comunemente indicata da una variabile chiamata `next`. +Le funzioni _Middleware_ sono funzioni che hanno accesso al [request object](/en/5x/api#req) (`req`), il [response object](/en/5x/api#res) (`res`), e la successiva funzione middleware nel ciclo request-response dell'applicazione. La funzione middleware successiva è comunemente indicata da una variabile chiamata `next`. Le funzioni Middleware possono eseguire le seguenti attività: -* Esegue qualsiasi codice. -* Effettuare modifiche alla richiesta e agli oggetti di risposta. -* Terminare il ciclo richiesta-risposta. -* Chiama la funzione middleware successiva nello stack. +- Esegue qualsiasi codice. +- Effettuare modifiche alla richiesta e agli oggetti di risposta. +- Terminare il ciclo richiesta-risposta. +- Chiama la funzione middleware successiva nello stack. Se la funzione middleware corrente non termina il ciclo richiesta-risposta, deve chiamare `next()` per passare il controllo alla successiva funzione middleware. In caso contrario, la richiesta sarà sospesa. Un'applicazione Express può utilizzare i seguenti tipi di middleware: -* [Application-level middleware](#middleware.application) -* [Router-level middleware](#middleware.router) -* [Gestione errori middleware](#middleware.error-handling) -* [Built-in middleware](#middleware.built-in) -* [middleware di terze parti](#middleware.third-party) +- [Application-level middleware](#middleware.application) +- [Router-level middleware](#middleware.router) +- [Gestione errori middleware](#middleware.error-handling) +- [Built-in middleware](#middleware.built-in) +- [middleware di terze parti](#middleware.third-party) È possibile caricare il middleware a livello di applicazione e router con un percorso di montaggio opzionale. È inoltre possibile caricare una serie di funzioni middleware insieme, che crea una sottopila del sistema middleware in un punto di montaggio. @@ -70,11 +70,11 @@ Illustra un sub-stack middleware che stampa la richiesta di informazioni per qua app.use( '/user/:id', (req, res, next) => { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); }, (req, res, next) => { - console. og('Request Type:', req.method); + console.og('Request Type:', req.method); next(); } ); @@ -140,17 +140,17 @@ Questo esempio mostra un array con un sub-stack middleware che gestisce le richi ```js function logOriginalUrl(req, res, next) { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); } function logMethod(req, res, next) { - console.log('Request Type:', req. ethod); + console.log('Request Type:', req.ethod); next(); } const logStuff = [logOriginalUrl, logMethod]; -app. et('/user/:id', logStuff, (req, res, next) => { +app.et('/user/:id', logStuff, (req, res, next) => { res.send('User Info'); }); ``` @@ -246,7 +246,7 @@ router. et('/user/:id', (req, res) => { -La gestione degli errori del middleware richiede sempre *four* argomenti. È necessario fornire quattro argomenti per +La gestione degli errori del middleware richiede sempre _four_ argomenti. È necessario fornire quattro argomenti per identificarlo come una funzione middleware di gestione degli errori. Anche se non è necessario utilizzare l'oggetto `next` , è necessario specificarlo per mantenere la firma. Otherwise, the `next` object will be interpreted as regular middleware and will fail to handle errors. @@ -271,9 +271,9 @@ che erano state precedentemente incluse con Express sono ora in moduli separati; Express ha le seguenti funzioni middleware integrate: -* [express.static](/en/5x/api#express.static) serve risorse statiche come file HTML, immagini e così via. -* [express.json](/en/5x/api#express.json) analizza le richieste in arrivo con i payload JSON. **NOTA: Disponibile con Express 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) analizza le richieste in arrivo con payload codificati con URL. **NOTA: Disponibile con Express 4.16.0+** +- [express.static](/en/5x/api#express.static) serve risorse statiche come file HTML, immagini e così via. +- [express.json](/en/5x/api#express.json) analizza le richieste in arrivo con i payload JSON. **NOTA: Disponibile con Express 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) analizza le richieste in arrivo con payload codificati con URL. **NOTA: Disponibile con Express 4.16.0+** ## middleware di terze parti diff --git a/src/content/docs/it/4x/guide/using-template-engines.mdx b/src/content/docs/it/4x/guide/using-template-engines.mdx index b9ca68f319..3548142cd6 100644 --- a/src/content/docs/it/4x/guide/using-template-engines.mdx +++ b/src/content/docs/it/4x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Scopri come integrare e utilizzare modelli di motori come Pug, Manu import Alert from '@components/primitives/Alert/Alert.astro'; -Un motore *modello* ti permette di utilizzare file di template statici nella tua applicazione. Al runtime, il modello del motore sostituisce le variabili +Un motore _modello_ ti permette di utilizzare file di template statici nella tua applicazione. Al runtime, il modello del motore sostituisce le variabili in un modello di file con valori reali, e trasforma il modello in un file HTML inviato al client. Questo approccio rende più facile progettare una pagina HTML. @@ -13,9 +13,9 @@ Il [generatore di applicazioni Express](/en/starter/generator) utilizza [Pug](ht Per rendere i file dei modelli, imposta le seguenti [proprietà delle impostazioni dell'applicazione](/en/4x/api#app.set), nel file `app.js` predefinito creato dal generatore: -* `views`, la directory dove si trovano i file del modello. Eg: `app.set('views', './views')`. +- `views`, la directory dove si trovano i file del modello. Eg: `app.set('views', './views')`. Questo valore predefinito è la directory `views` nella directory radice dell'applicazione. -* `view engine`, il modello motore da usare. Ad esempio, per usare il motore modello Pug: `app.set('view engine', 'pug')`. +- `view engine`, il modello motore da usare. Ad esempio, per usare il motore modello Pug: `app.set('view engine', 'pug')`. Quindi installare il corrispondente pacchetto npm del motore del modello; per esempio per installare Pug: diff --git a/src/content/docs/it/4x/guide/writing-middleware.mdx b/src/content/docs/it/4x/guide/writing-middleware.mdx index ef60a1ae15..91e7a122a9 100644 --- a/src/content/docs/it/4x/guide/writing-middleware.mdx +++ b/src/content/docs/it/4x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Scopri come scrivere funzioni middleware personalizzate per le appl import Alert from '@components/primitives/Alert/Alert.astro'; -Le funzioni *Middleware* sono funzioni che hanno accesso al [request object](/en/5x/api#req) (`req`), il [response object](/en/5x/api#res) (`res`), e la funzione `next` nel ciclo request-response dell'applicazione. La funzione `next` è una funzione nel router Express che, quando invocato, esegue il middleware con successo al middleware corrente. +Le funzioni _Middleware_ sono funzioni che hanno accesso al [request object](/en/5x/api#req) (`req`), il [response object](/en/5x/api#res) (`res`), e la funzione `next` nel ciclo request-response dell'applicazione. La funzione `next` è una funzione nel router Express che, quando invocato, esegue il middleware con successo al middleware corrente. Le funzioni Middleware possono eseguire le seguenti attività: -* Esegue qualsiasi codice. -* Effettuare modifiche alla richiesta e agli oggetti di risposta. -* Terminare il ciclo richiesta-risposta. -* Chiama il prossimo middleware nello stack. +- Esegue qualsiasi codice. +- Effettuare modifiche alla richiesta e agli oggetti di risposta. +- Terminare il ciclo richiesta-risposta. +- Chiama il prossimo middleware nello stack. Se la funzione middleware corrente non termina il ciclo richiesta-risposta, deve chiamare `next()` per passare il controllo alla successiva funzione middleware. In caso contrario, la richiesta sarà sospesa. @@ -40,8 +40,8 @@ Metodo
    HTTP per il quale si applica la funzio
    - Argomento HTTP risposta alla funzione middleware, chiamato "res" dalla convenzione - . + Argomento HTTP risposta alla funzione middleware, chiamato "res" + dalla convenzione .
    HTTP richiede l'argomento alla funzione middleware, chiamata "req" per convenzione.
    @@ -100,7 +100,7 @@ const express = require('express'); const app = express(); const myLogger = function (req, res, next) { - console. og('LOGGED'); + console.og('LOGGED'); next(); }; @@ -140,16 +140,16 @@ const express = require('express'); const app = express(); const requestTime = function (req, res, next) { - req. equestTime = Date.now(); + req.equestTime = Date.now(); next(); }; app.use(requestTime); -app. et('/', (req, res) => { +app.et('/', (req, res) => { let responseText = 'Ciao Mondo!
    '; responseText += `Richiesto a: ${req.requestTime}`; - res. end(responseText); + res.end(responseText); }); app.listen(3000); @@ -183,7 +183,7 @@ const cookieValidator = require('. cookieValidator'); const app = express(); async function validateCookies(req, res, next) { - await cookieValidator(req. ookies); + await cookieValidator(req.ookies); next(); } @@ -192,7 +192,7 @@ app.use(cookieParser()); app.use(validateCookies); // error handler -app. se((err, req, res, next) => { +app.se((err, req, res, next) => { res.status(400).send(err.message); }); @@ -220,7 +220,7 @@ Se hai bisogno del tuo middleware per essere configurabile, esporta una funzione File: `my-middleware.js` ```js -modulo. xports = function (options) { +modulo.xports = function (options) { return function (req, res, next) { // Implementa la funzione middleware basata sulle opzioni object next(); diff --git a/src/content/docs/it/4x/starter/basic-routing.mdx b/src/content/docs/it/4x/starter/basic-routing.mdx index e78f4b9025..f9777989fc 100644 --- a/src/content/docs/it/4x/starter/basic-routing.mdx +++ b/src/content/docs/it/4x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Impara i fondamenti del routing nelle applicazioni Express.js, tra import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* si riferisce alla determinazione di come un'applicazione risponde a una richiesta di client a un determinato endpoint, che è un URI (o percorso) e un metodo di richiesta HTTP specifico (GET, POST, e così via). +_Routing_ si riferisce alla determinazione di come un'applicazione risponde a una richiesta di client a un determinato endpoint, che è un URI (o percorso) e un metodo di richiesta HTTP specifico (GET, POST, e così via). Ogni percorso può avere una o più funzioni di gestore, che vengono eseguite quando il percorso è abbinato. @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); Dove: -* `app` è un'istanza di `express`. -* `METHOD` è un [metodo di richiesta HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in minuscolo. -* `PATH` è un percorso sul server. -* `HANDLER` è la funzione eseguita quando il percorso è corrispondente. +- `app` è un'istanza di `express`. +- `METHOD` è un [metodo di richiesta HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in minuscolo. +- `PATH` è un percorso sul server. +- `HANDLER` è la funzione eseguita quando il percorso è corrispondente. diff --git a/src/content/docs/it/4x/starter/examples.mdx b/src/content/docs/it/4x/starter/examples.mdx index a1d1b331f8..2165c04250 100644 --- a/src/content/docs/it/4x/starter/examples.mdx +++ b/src/content/docs/it/4x/starter/examples.mdx @@ -5,41 +5,41 @@ description: Esplora una raccolta di esempi di applicazioni Express.js che copro import Alert from '@components/primitives/Alert/Alert.astro'; -* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Autenticazione con login e password -* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - Negoziazione di contenuti HTTP -* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Lavorare con sessioni basate su cookie -* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Lavorare con i cookie -* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Trasferimento dei file al client -* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Lavorare con il template JavaScript incorporato (ejs) -* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Creazione pagine di errore -* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Lavorare con middleware errore -* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Gestore semplice della richiesta -* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown come modello motore -* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Lavorare con più router Express -* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - controller in stile MVC -* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Monitoraggio delle attività degli utenti online con pacchetti `online` e `redis` -* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Lavorare con i parametri del percorso -* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Operazioni HTTP multiple sulla stessa risorsa -* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organizzare i percorsi utilizzando una mappa -* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Lavorare con il middleware del percorso -* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizzare percorsi per ogni risorsa -* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Cerca API -* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - sessioni utente -* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Servire file statici -* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Lavorare con gli host virtuali -* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Visualizzazione dinamica -* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Salvataggio dei dati nell'oggetto richiesta tra le chiamate middleware -* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Servizio API semplice +- [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Autenticazione con login e password +- [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - Negoziazione di contenuti HTTP +- [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Lavorare con sessioni basate su cookie +- [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Lavorare con i cookie +- [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Trasferimento dei file al client +- [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Lavorare con il template JavaScript incorporato (ejs) +- [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Creazione pagine di errore +- [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Lavorare con middleware errore +- [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Gestore semplice della richiesta +- [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown come modello motore +- [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Lavorare con più router Express +- [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - controller in stile MVC +- [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Monitoraggio delle attività degli utenti online con pacchetti `online` e `redis` +- [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Lavorare con i parametri del percorso +- [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Operazioni HTTP multiple sulla stessa risorsa +- [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organizzare i percorsi utilizzando una mappa +- [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Lavorare con il middleware del percorso +- [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizzare percorsi per ogni risorsa +- [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Cerca API +- [session](https://github.com/expressjs/express/tree/4.x/examples/session) - sessioni utente +- [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Servire file statici +- [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Lavorare con gli host virtuali +- [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Visualizzazione dinamica +- [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Salvataggio dei dati nell'oggetto richiesta tra le chiamate middleware +- [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Servizio API semplice ## Esempi aggiuntivi Questi sono alcuni esempi aggiuntivi con integrazioni più estese. - Queste informazioni si riferiscono a siti, prodotti o moduli di terze parti che non sono mantenuti dal team - Expressjs. L'elenco qui non costituisce un'approvazione o una raccomandazione da parte del team di progetto - Expressjs. + Queste informazioni si riferiscono a siti, prodotti o moduli di terze parti che non sono mantenuti + dal team Expressjs. L'elenco qui non costituisce un'approvazione o una raccomandazione da parte + del team di progetto Expressjs. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app con Express e Next.js utilizzando [Prisma](https://www.npmjs.com/package/prisma) come ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app con Express e Next.js utilizzando [Prisma](https://www.npmjs.com/package/prisma) come ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM diff --git a/src/content/docs/it/4x/starter/generator.mdx b/src/content/docs/it/4x/starter/generator.mdx index c7504927ad..1b0eeaa660 100644 --- a/src/content/docs/it/4x/starter/generator.mdx +++ b/src/content/docs/it/4x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force force sulla directory non vuota ``` -Ad esempio, il seguente crea un'app Express chiamata *myapp*. L'app verrà creata in una cartella chiamata *myapp* nella directory di lavoro corrente e il motore di visualizzazione sarà impostato su Pug: +Ad esempio, il seguente crea un'app Express chiamata _myapp_. L'app verrà creata in una cartella chiamata _myapp_ nella directory di lavoro corrente e il motore di visualizzazione sarà impostato su Pug: ```bash $ express --view=pug myapp diff --git a/src/content/docs/it/4x/starter/hello-world.mdx b/src/content/docs/it/4x/starter/hello-world.mdx index ebb1cf18e4..4b4df6bcfe 100644 --- a/src/content/docs/it/4x/starter/hello-world.mdx +++ b/src/content/docs/it/4x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Incorporato qui sotto è essenzialmente l'app Express più semplice che puoi creare. Si tratta di un singolo file app -— *non* quello che si otterrebbe se si utilizza il [Express generator](/en/starter/generator), che +— _non_ quello che si otterrebbe se si utilizza il [Express generator](/en/starter/generator), che crea il ponteggio per un'app completa con numerosi file JavaScript, modelli Jade e sottodirectory per vari scopi. @@ -20,7 +20,7 @@ const app = express(); const port = 3000; app.get('/', (req, res) => { - res. end('Hello World!'); + res.end('Hello World!'); }); app.listen(port, () => { @@ -29,7 +29,7 @@ app.listen(port, () => { ``` Questa app avvia un server e ascolta la porta 3000 per le connessioni. L'app risponde con "Ciao Mondo!" per le richieste -all'URL radice (`/`) o *route*. Per ogni altro percorso, risponderà con un **404 non trovato**. +all'URL radice (`/`) o _route_. Per ogni altro percorso, risponderà con un **404 non trovato**. ## Esecuzione Localmente diff --git a/src/content/docs/it/5x/guide/behind-proxies.mdx b/src/content/docs/it/5x/guide/behind-proxies.mdx index eeb3cb8160..a31c0ad959 100644 --- a/src/content/docs/it/5x/guide/behind-proxies.mdx +++ b/src/content/docs/it/5x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ Quando si imposta a `true`, è importante assicurarsi che l'ultimo proxy inverso Un indirizzo IP, una sottorete, o un array di indirizzi IP e sottoreti a cui fidarsi come proxy inverso. Il seguente elenco mostra i nomi pre-configurati delle sottorete -* loopback - `127.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` È possibile impostare gli indirizzi IP in uno dei seguenti modi: @@ -86,16 +86,18 @@ Abilitare il `trust proxy` avrà il seguente impatto:
    • - Il valore di [req.hostname](/en/api#req.hostname) è derivato dal valore impostato nell'intestazione - `X-Forwarded-Host`, che può essere impostato dal cliente o dal proxy. + Il valore di [req.hostname](/en/api#req.hostname) è derivato dal valore impostato + nell'intestazione `X-Forwarded-Host`, che può essere impostato dal cliente o dal proxy.
    • - `X-Forwarded-Proto` può essere impostato dal proxy inverso per dire all'app se si tratta di `↓ ` o - `http` o anche di un nome non valido. Questo valore è riflesso da [req.protocol](/en/api#req.protocol). + `X-Forwarded-Proto` può essere impostato dal proxy inverso per dire all'app se si tratta di `↓ ` + o `http` o anche di un nome non valido. Questo valore è riflesso da + [req.protocol](/en/api#req.protocol).
    • - I valori [req.ip](/en/api#req.ip) e [req.ips](/en/api#req.ips) sono popolati in base all'indirizzo del socket - e all'intestazione `X-Forwarded-For`, a partire dal primo indirizzo non fidato. + I valori [req.ip](/en/api#req.ip) e [req.ips](/en/api#req.ips) sono popolati in base + all'indirizzo del socket e all'intestazione `X-Forwarded-For`, a partire dal primo indirizzo non + fidato.
    diff --git a/src/content/docs/it/5x/guide/error-handling.mdx b/src/content/docs/it/5x/guide/error-handling.mdx index affc346d07..3378bd2b75 100644 --- a/src/content/docs/it/5x/guide/error-handling.mdx +++ b/src/content/docs/it/5x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Capire come Express.js gestisce gli errori nel codice sincrono e as import Alert from '@components/primitives/Alert/Alert.astro'; -*Error Handling* si riferisce a come Express cattura ed elabora gli errori +_Error Handling_ si riferisce a come Express cattura ed elabora gli errori che si verificano in modo sincrono e asincrono. Express viene fornito con un gestore di errore predefinito quindi non è necessario scrivere il proprio per iniziare. @@ -30,11 +30,11 @@ catturarli ed elaborarli. Per esempio: ```js app.get('/', (req, res, next) => { - fs. eadFile('/file-does-not-exist', (err, data) => { + fs.eadFile('/file-does-not-exist', (err, data) => { if (err) { next(err); // Passa gli errori a Express. } else { - res. end(dati); + res.end(dati); } }); }); @@ -103,10 +103,10 @@ che restituiscono le promesse. Per esempio: ```js app.get('/', (req, res, next) => { Promise.resolve() - . hen(() => { + .hen(() => { throw new Error('BROKEN'); }) - . atch(next); // Gli errori saranno passati a Express. + .atch(next); // Gli errori saranno passati a Express. }); ``` @@ -120,13 +120,13 @@ catching, riducendo il codice asincrono a qualcosa di banale. Per esempio: ```js app.get('/', [ function (req, res, next) { - fs. eadFile('/maybe-valid-file', 'utf-8', (err, data) => { - res.locals. ata = dati; + fs.eadFile('/maybe-valid-file', 'utf-8', (err, data) => { + res.locals.ata = dati; next(err); }); }, function (req, res) { - res. ocals.data = res.locals.data.split(',')[1]; + res.ocals.data = res.locals.data.split(',')[1]; res.send(res.locals.data); }, ]); @@ -161,12 +161,12 @@ Imposta la variabile d'ambiente `NODE_ENV` su `production`, per eseguire l'appli Quando viene scritto un errore, alla risposta vengono aggiunte le seguenti informazioni: -* Il `res.statusCode` è impostato da `err.status` (o `err.statusCode`). Se +- Il `res.statusCode` è impostato da `err.status` (o `err.statusCode`). Se questo valore è al di fuori dell'intervallo 4xx o 5xx, sarà impostato a 500. -* Il `res.statusMessage` è impostato in base al codice di stato. -* Il corpo sarà l'HTML del messaggio del codice di stato quando in ambiente di produzione +- Il `res.statusMessage` è impostato in base al codice di stato. +- Il corpo sarà l'HTML del messaggio del codice di stato quando in ambiente di produzione , altrimenti sarà `err.stack`. -* Qualsiasi intestazione specificata in un oggetto `err.headers`. +- Qualsiasi intestazione specificata in un oggetto `err.headers`. Se chiami `next()` con un errore dopo aver iniziato a scrivere la risposta (ad esempio, se riscontri un errore durante lo streaming della risposta @@ -212,12 +212,12 @@ const bodyParser = require('body-parser'); const methodOverride = require('method-override'); app.use( - bodyParser. rlencoded({ + bodyParser.rlencoded({ extended: true, }) ); app.use(bodyParser.json()); -app. se(methodOverride()); +app.se(methodOverride()); app.use((err, req, res, next) => { // logic }); @@ -258,12 +258,12 @@ function logErrors(err, req, res, next) { Anche in questo esempio, `clientErrorHandler` è definito come segue; in questo caso, l'errore viene esplicitamente passato a quello successivo. -Nota che quando *non* chiama "next" in una funzione di gestione degli errori, sei responsabile della scrittura (e della fine) della risposta. In caso contrario, tali richieste saranno "appese" e non saranno ammissibili per la raccolta rifiuti. +Nota che quando _non_ chiama "next" in una funzione di gestione degli errori, sei responsabile della scrittura (e della fine) della risposta. In caso contrario, tali richieste saranno "appese" e non saranno ammissibili per la raccolta rifiuti. ```js function clientErrorHandler(err, req, res, next) { if (req.xhr) { - res.status(500). end({ error: 'Something failed!' }); + res.status(500).end({ error: 'Something failed!' }); } else { next(err); } @@ -285,7 +285,7 @@ Se si dispone di un gestore del percorso con molteplici funzioni di callback, è app.get( '/a_route_behind_paywall', (req, res, next) => { - if (!req.user. asPaid) { + if (!req.user.asPaid) { // continue handling this request next('route'); } else { @@ -293,9 +293,9 @@ app.get( } }, (req, res, next) => { - PaidContent. ind((err, doc) => { + PaidContent.ind((err, doc) => { if (err) return next(err); - res. son(doc); + res.son(doc); }); } ); diff --git a/src/content/docs/it/5x/guide/routing.mdx b/src/content/docs/it/5x/guide/routing.mdx index 4a65c235d4..19873bbdf3 100644 --- a/src/content/docs/it/5x/guide/routing.mdx +++ b/src/content/docs/it/5x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Scopri come definire e utilizzare i percorsi nelle applicazioni Exp import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* si riferisce a come gli endpoint di un'applicazione (URI) rispondono alle richieste del client. +_Routing_ si riferisce a come gli endpoint di un'applicazione (URI) rispondono alle richieste del client. Per un'introduzione al routing, vedere [Instradamento di base](/en/starter/basic-routing). Definisci il routing usando metodi dell'oggetto `app` Express che corrispondono ai metodi HTTP; @@ -40,11 +40,11 @@ Il seguente codice è un esempio di percorsi definiti per il `GET` e i metodi `P ```js // GET method route app.get('/', (req, res) => { - res. end('Richiesta GET alla homepage'); + res.end('Richiesta GET alla homepage'); }); // POST metodo percorso -app. ost('/', (req, res) => { +app.ost('/', (req, res) => { res.send('POST request to the homepage'); }); ``` @@ -52,7 +52,7 @@ app. ost('/', (req, res) => { Express supporta metodi che corrispondono a tutti i metodi di richiesta HTTP: `get`, `post`, e così via. Per un elenco completo, vedere [app.METHOD](/en/5x/api#app.METHOD). -C'è un metodo di routing speciale, `app.all()`, utilizzato per caricare le funzioni middleware in un percorso per *tutti* i metodi di richiesta HTTP. Ad esempio, il seguente gestore viene eseguito per le richieste al percorso `"/secret"` se si utilizza `GET`, `POST`, `PUT`, `DELETE`, o qualsiasi altro metodo di richiesta HTTP supportato nel [modulo http](https://nodejs.org/api/http.html#http_http_methods). +C'è un metodo di routing speciale, `app.all()`, utilizzato per caricare le funzioni middleware in un percorso per _tutti_ i metodi di richiesta HTTP. Ad esempio, il seguente gestore viene eseguito per le richieste al percorso `"/secret"` se si utilizza `GET`, `POST`, `PUT`, `DELETE`, o qualsiasi altro metodo di richiesta HTTP supportato nel [modulo http](https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -244,10 +244,10 @@ In Express 4.x, il ca ```js app.get('/user/:id', (req, res, next) => { - if (req.params. d === '0') { + if (req.params.d === '0') { return next('route'); } - res. end(`User ${req.params.id}`); + res.end(`User ${req.params.id}`); }); app.get('/user/:id', (req, res) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { In questo esempio: -* `GET /user/5` → gestito dal primo percorso → invia "User 5" -* `GET /user/0` → prima rotta chiama `next('route')`, saltando al prossimo percorso corrispondente `/user/:id` +- `GET /user/5` → gestito dal primo percorso → invia "User 5" +- `GET /user/0` → prima rotta chiama `next('route')`, saltando al prossimo percorso corrispondente `/user/:id` I gestori del percorso possono essere nella forma di una funzione, una serie di funzioni, o combinazioni di entrambi, come mostrato negli esempi seguenti. @@ -276,11 +276,11 @@ Più di una funzione di callback può gestire un percorso (assicurati di specifi app.get( '/example/b', (req, res, next) => { - console. og('la risposta verrà inviata dalla funzione successiva . .'); + console.og('la risposta verrà inviata dalla funzione successiva . .'); next(); }, (req, res) => { - res. end('Ciao da B!'); + res.end('Ciao da B!'); } ); ``` @@ -289,17 +289,17 @@ Un array di funzioni di callback può gestire un percorso. Per esempio: ```js const cb0 = function (req, res, next) { - console. og('CB0'); + console.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; const cb2 = function (req, res) { - res. end('Ciao da C!'); + res.end('Ciao da C!'); }; app.get('/example/c', [cb0, cb1, cb2]); @@ -309,24 +309,24 @@ Una combinazione di funzioni indipendenti e matrici di funzioni può gestire un ```js const cb0 = function (req, res, next) { - console. og('CB0'); + console.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; -app. et( +app.et( '/example/d', [cb0, cb1], (req, res, next) => { - console. og('la risposta verrà inviata dalla funzione successiva . .'); + console.og('la risposta verrà inviata dalla funzione successiva . .'); next(); }, (req, res) => { - res. end('Ciao da D!'); + res.end('Ciao da D!'); } ); ``` @@ -358,14 +358,14 @@ Ecco un esempio di router incatenati che sono definiti utilizzando `app.route()` app .route('/book') .get((req, res) => { - res. end('Ottieni un libro casuale'); + res.end('Ottieni un libro casuale'); }) - . ost((req, res) => { + .ost((req, res) => { res.send('Add a book'); }) - . ut((req, res) => { + .ut((req, res) => { res.send('Aggiorna il libro'); -}); + }); ``` ## express.Router diff --git a/src/content/docs/it/5x/guide/using-middleware.mdx b/src/content/docs/it/5x/guide/using-middleware.mdx index d076967bee..25d334aeb0 100644 --- a/src/content/docs/it/5x/guide/using-middleware.mdx +++ b/src/content/docs/it/5x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express è un framework web routing e middleware che ha funzionalità minime proprie: Un'applicazione Express è essenzialmente una serie di chiamate di funzioni middleware. -Le funzioni *Middleware* sono funzioni che hanno accesso al [request object](/en/5x/api#req) (`req`), il [response object](/en/5x/api#res) (`res`), e la successiva funzione middleware nel ciclo request-response dell'applicazione. La funzione middleware successiva è comunemente indicata da una variabile chiamata `next`. +Le funzioni _Middleware_ sono funzioni che hanno accesso al [request object](/en/5x/api#req) (`req`), il [response object](/en/5x/api#res) (`res`), e la successiva funzione middleware nel ciclo request-response dell'applicazione. La funzione middleware successiva è comunemente indicata da una variabile chiamata `next`. Le funzioni Middleware possono eseguire le seguenti attività: -* Esegue qualsiasi codice. -* Effettuare modifiche alla richiesta e agli oggetti di risposta. -* Terminare il ciclo richiesta-risposta. -* Chiama la funzione middleware successiva nello stack. +- Esegue qualsiasi codice. +- Effettuare modifiche alla richiesta e agli oggetti di risposta. +- Terminare il ciclo richiesta-risposta. +- Chiama la funzione middleware successiva nello stack. Se la funzione middleware corrente non termina il ciclo richiesta-risposta, deve chiamare `next()` per passare il controllo alla successiva funzione middleware. In caso contrario, la richiesta sarà sospesa. Un'applicazione Express può utilizzare i seguenti tipi di middleware: -* [Application-level middleware](#middleware.application) -* [Router-level middleware](#middleware.router) -* [Gestione errori middleware](#middleware.error-handling) -* [Built-in middleware](#middleware.built-in) -* [middleware di terze parti](#middleware.third-party) +- [Application-level middleware](#middleware.application) +- [Router-level middleware](#middleware.router) +- [Gestione errori middleware](#middleware.error-handling) +- [Built-in middleware](#middleware.built-in) +- [middleware di terze parti](#middleware.third-party) È possibile caricare il middleware a livello di applicazione e router con un percorso di montaggio opzionale. È inoltre possibile caricare una serie di funzioni middleware insieme, che crea una sottopila del sistema middleware in un punto di montaggio. @@ -70,11 +70,11 @@ Illustra un sub-stack middleware che stampa la richiesta di informazioni per qua app.use( '/user/:id', (req, res, next) => { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); }, (req, res, next) => { - console. og('Request Type:', req.method); + console.og('Request Type:', req.method); next(); } ); @@ -140,17 +140,17 @@ Questo esempio mostra un array con un sub-stack middleware che gestisce le richi ```js function logOriginalUrl(req, res, next) { - console.log('Request URL:', req. riginalUrl); + console.log('Request URL:', req.riginalUrl); next(); } function logMethod(req, res, next) { - console.log('Request Type:', req. ethod); + console.log('Request Type:', req.ethod); next(); } const logStuff = [logOriginalUrl, logMethod]; -app. et('/user/:id', logStuff, (req, res, next) => { +app.et('/user/:id', logStuff, (req, res, next) => { res.send('User Info'); }); ``` @@ -246,7 +246,7 @@ router. et('/user/:id', (req, res) => { -La gestione degli errori del middleware richiede sempre *four* argomenti. È necessario fornire quattro argomenti per +La gestione degli errori del middleware richiede sempre _four_ argomenti. È necessario fornire quattro argomenti per identificarlo come una funzione middleware di gestione degli errori. Anche se non è necessario utilizzare l'oggetto `next` , è necessario specificarlo per mantenere la firma. Otherwise, the `next` object will be interpreted as regular middleware and will fail to handle errors. @@ -271,9 +271,9 @@ che erano state precedentemente incluse con Express sono ora in moduli separati; Express ha le seguenti funzioni middleware integrate: -* [express.static](/en/5x/api#express.static) serve risorse statiche come file HTML, immagini e così via. -* [express.json](/en/5x/api#express.json) analizza le richieste in arrivo con i payload JSON. **NOTA: Disponibile con Express 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) analizza le richieste in arrivo con payload codificati con URL. **NOTA: Disponibile con Express 4.16.0+** +- [express.static](/en/5x/api#express.static) serve risorse statiche come file HTML, immagini e così via. +- [express.json](/en/5x/api#express.json) analizza le richieste in arrivo con i payload JSON. **NOTA: Disponibile con Express 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) analizza le richieste in arrivo con payload codificati con URL. **NOTA: Disponibile con Express 4.16.0+** ## middleware di terze parti diff --git a/src/content/docs/it/5x/guide/using-template-engines.mdx b/src/content/docs/it/5x/guide/using-template-engines.mdx index b9ca68f319..3548142cd6 100644 --- a/src/content/docs/it/5x/guide/using-template-engines.mdx +++ b/src/content/docs/it/5x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Scopri come integrare e utilizzare modelli di motori come Pug, Manu import Alert from '@components/primitives/Alert/Alert.astro'; -Un motore *modello* ti permette di utilizzare file di template statici nella tua applicazione. Al runtime, il modello del motore sostituisce le variabili +Un motore _modello_ ti permette di utilizzare file di template statici nella tua applicazione. Al runtime, il modello del motore sostituisce le variabili in un modello di file con valori reali, e trasforma il modello in un file HTML inviato al client. Questo approccio rende più facile progettare una pagina HTML. @@ -13,9 +13,9 @@ Il [generatore di applicazioni Express](/en/starter/generator) utilizza [Pug](ht Per rendere i file dei modelli, imposta le seguenti [proprietà delle impostazioni dell'applicazione](/en/4x/api#app.set), nel file `app.js` predefinito creato dal generatore: -* `views`, la directory dove si trovano i file del modello. Eg: `app.set('views', './views')`. +- `views`, la directory dove si trovano i file del modello. Eg: `app.set('views', './views')`. Questo valore predefinito è la directory `views` nella directory radice dell'applicazione. -* `view engine`, il modello motore da usare. Ad esempio, per usare il motore modello Pug: `app.set('view engine', 'pug')`. +- `view engine`, il modello motore da usare. Ad esempio, per usare il motore modello Pug: `app.set('view engine', 'pug')`. Quindi installare il corrispondente pacchetto npm del motore del modello; per esempio per installare Pug: diff --git a/src/content/docs/it/5x/guide/writing-middleware.mdx b/src/content/docs/it/5x/guide/writing-middleware.mdx index 14157fe349..cea8997d8d 100644 --- a/src/content/docs/it/5x/guide/writing-middleware.mdx +++ b/src/content/docs/it/5x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Scopri come scrivere funzioni middleware personalizzate per le appl import Alert from '@components/primitives/Alert/Alert.astro'; -Le funzioni *Middleware* sono funzioni che hanno accesso al [request object](/en/5x/api#req) (`req`), il [response object](/en/5x/api#res) (`res`), e la funzione `next` nel ciclo request-response dell'applicazione. La funzione `next` è una funzione nel router Express che, quando invocato, esegue il middleware con successo al middleware corrente. +Le funzioni _Middleware_ sono funzioni che hanno accesso al [request object](/en/5x/api#req) (`req`), il [response object](/en/5x/api#res) (`res`), e la funzione `next` nel ciclo request-response dell'applicazione. La funzione `next` è una funzione nel router Express che, quando invocato, esegue il middleware con successo al middleware corrente. Le funzioni Middleware possono eseguire le seguenti attività: -* Esegue qualsiasi codice. -* Effettuare modifiche alla richiesta e agli oggetti di risposta. -* Terminare il ciclo richiesta-risposta. -* Chiama il prossimo middleware nello stack. +- Esegue qualsiasi codice. +- Effettuare modifiche alla richiesta e agli oggetti di risposta. +- Terminare il ciclo richiesta-risposta. +- Chiama il prossimo middleware nello stack. Se la funzione middleware corrente non termina il ciclo richiesta-risposta, deve chiamare `next()` per passare il controllo alla successiva funzione middleware. In caso contrario, la richiesta sarà sospesa. @@ -70,7 +70,7 @@ const express = require('express'); const app = express(); const myLogger = function (req, res, next) { - console. og('LOGGED'); + console.og('LOGGED'); next(); }; @@ -110,16 +110,16 @@ const express = require('express'); const app = express(); const requestTime = function (req, res, next) { - req. equestTime = Date.now(); + req.equestTime = Date.now(); next(); }; app.use(requestTime); -app. et('/', (req, res) => { +app.et('/', (req, res) => { let responseText = 'Ciao Mondo!
    '; responseText += `Richiesto a: ${req.requestTime}`; - res. end(responseText); + res.end(responseText); }); app.listen(3000); @@ -153,7 +153,7 @@ const cookieValidator = require('. cookieValidator'); const app = express(); async function validateCookies(req, res, next) { - await cookieValidator(req. ookies); + await cookieValidator(req.ookies); next(); } @@ -162,7 +162,7 @@ app.use(cookieParser()); app.use(validateCookies); // error handler -app. se((err, req, res, next) => { +app.se((err, req, res, next) => { res.status(400).send(err.message); }); @@ -190,7 +190,7 @@ Se hai bisogno del tuo middleware per essere configurabile, esporta una funzione File: `my-middleware.js` ```js -modulo. xports = function (options) { +modulo.xports = function (options) { return function (req, res, next) { // Implementa la funzione middleware basata sulle opzioni object next(); diff --git a/src/content/docs/it/5x/starter/basic-routing.mdx b/src/content/docs/it/5x/starter/basic-routing.mdx index e78f4b9025..f9777989fc 100644 --- a/src/content/docs/it/5x/starter/basic-routing.mdx +++ b/src/content/docs/it/5x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Impara i fondamenti del routing nelle applicazioni Express.js, tra import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* si riferisce alla determinazione di come un'applicazione risponde a una richiesta di client a un determinato endpoint, che è un URI (o percorso) e un metodo di richiesta HTTP specifico (GET, POST, e così via). +_Routing_ si riferisce alla determinazione di come un'applicazione risponde a una richiesta di client a un determinato endpoint, che è un URI (o percorso) e un metodo di richiesta HTTP specifico (GET, POST, e così via). Ogni percorso può avere una o più funzioni di gestore, che vengono eseguite quando il percorso è abbinato. @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); Dove: -* `app` è un'istanza di `express`. -* `METHOD` è un [metodo di richiesta HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in minuscolo. -* `PATH` è un percorso sul server. -* `HANDLER` è la funzione eseguita quando il percorso è corrispondente. +- `app` è un'istanza di `express`. +- `METHOD` è un [metodo di richiesta HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in minuscolo. +- `PATH` è un percorso sul server. +- `HANDLER` è la funzione eseguita quando il percorso è corrispondente. diff --git a/src/content/docs/it/5x/starter/examples.mdx b/src/content/docs/it/5x/starter/examples.mdx index db38886bfd..54c2acb2e4 100644 --- a/src/content/docs/it/5x/starter/examples.mdx +++ b/src/content/docs/it/5x/starter/examples.mdx @@ -7,31 +7,31 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Questa pagina contiene un elenco di esempi utilizzando Express. -* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Autenticazione con login e password -* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - Negoziazione di contenuti HTTP -* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Lavorare con sessioni basate su cookie -* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Lavorare con i cookie -* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Trasferimento dei file al client -* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Lavorare con il template JavaScript incorporato (ejs) -* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Creazione pagine di errore -* [error](https://github.com/expressjs/express/tree/master/examples/error) - Lavorare con middleware errore -* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Gestore semplice della richiesta -* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown come modello motore -* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Lavorare con più router Express -* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - controller in stile MVC -* [online](https://github.com/expressjs/express/tree/master/examples/online) - Monitoraggio delle attività degli utenti online con pacchetti `online` e `redis` -* [params](https://github.com/expressjs/express/tree/master/examples/params) - Lavorare con i parametri del percorso -* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Operazioni HTTP multiple sulla stessa risorsa -* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organizzare i percorsi utilizzando una mappa -* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Lavorare con il middleware del percorso -* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizzare percorsi per ogni risorsa -* [search](https://github.com/expressjs/express/tree/master/examples/search) - Cerca API -* [session](https://github.com/expressjs/express/tree/master/examples/session) - sessioni utente -* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Servire file statici -* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Lavorare con gli host virtuali -* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Visualizzazione dinamica -* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Salvataggio dei dati nell'oggetto richiesta tra le chiamate middleware -* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Servizio API semplice +- [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Autenticazione con login e password +- [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - Negoziazione di contenuti HTTP +- [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Lavorare con sessioni basate su cookie +- [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Lavorare con i cookie +- [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Trasferimento dei file al client +- [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Lavorare con il template JavaScript incorporato (ejs) +- [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Creazione pagine di errore +- [error](https://github.com/expressjs/express/tree/master/examples/error) - Lavorare con middleware errore +- [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Gestore semplice della richiesta +- [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown come modello motore +- [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Lavorare con più router Express +- [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - controller in stile MVC +- [online](https://github.com/expressjs/express/tree/master/examples/online) - Monitoraggio delle attività degli utenti online con pacchetti `online` e `redis` +- [params](https://github.com/expressjs/express/tree/master/examples/params) - Lavorare con i parametri del percorso +- [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Operazioni HTTP multiple sulla stessa risorsa +- [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organizzare i percorsi utilizzando una mappa +- [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Lavorare con il middleware del percorso +- [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizzare percorsi per ogni risorsa +- [search](https://github.com/expressjs/express/tree/master/examples/search) - Cerca API +- [session](https://github.com/expressjs/express/tree/master/examples/session) - sessioni utente +- [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Servire file statici +- [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Lavorare con gli host virtuali +- [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Visualizzazione dinamica +- [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Salvataggio dei dati nell'oggetto richiesta tra le chiamate middleware +- [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Servizio API semplice ## Esempi aggiuntivi @@ -45,5 +45,5 @@ Expressjs. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app con Express e Next.js utilizzando [Prisma](https://www.npmjs.com/package/prisma) come ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app con Express e Next.js utilizzando [Prisma](https://www.npmjs.com/package/prisma) come ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM diff --git a/src/content/docs/it/5x/starter/generator.mdx b/src/content/docs/it/5x/starter/generator.mdx index c7504927ad..1b0eeaa660 100644 --- a/src/content/docs/it/5x/starter/generator.mdx +++ b/src/content/docs/it/5x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force force sulla directory non vuota ``` -Ad esempio, il seguente crea un'app Express chiamata *myapp*. L'app verrà creata in una cartella chiamata *myapp* nella directory di lavoro corrente e il motore di visualizzazione sarà impostato su     Pug: +Ad esempio, il seguente crea un'app Express chiamata _myapp_. L'app verrà creata in una cartella chiamata _myapp_ nella directory di lavoro corrente e il motore di visualizzazione sarà impostato su Pug: ```bash $ express --view=pug myapp diff --git a/src/content/docs/it/5x/starter/hello-world.mdx b/src/content/docs/it/5x/starter/hello-world.mdx index ebb1cf18e4..4b4df6bcfe 100644 --- a/src/content/docs/it/5x/starter/hello-world.mdx +++ b/src/content/docs/it/5x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Incorporato qui sotto è essenzialmente l'app Express più semplice che puoi creare. Si tratta di un singolo file app -— *non* quello che si otterrebbe se si utilizza il [Express generator](/en/starter/generator), che +— _non_ quello che si otterrebbe se si utilizza il [Express generator](/en/starter/generator), che crea il ponteggio per un'app completa con numerosi file JavaScript, modelli Jade e sottodirectory per vari scopi. @@ -20,7 +20,7 @@ const app = express(); const port = 3000; app.get('/', (req, res) => { - res. end('Hello World!'); + res.end('Hello World!'); }); app.listen(port, () => { @@ -29,7 +29,7 @@ app.listen(port, () => { ``` Questa app avvia un server e ascolta la porta 3000 per le connessioni. L'app risponde con "Ciao Mondo!" per le richieste -all'URL radice (`/`) o *route*. Per ogni altro percorso, risponderà con un **404 non trovato**. +all'URL radice (`/`) o _route_. Per ogni altro percorso, risponderà con un **404 non trovato**. ## Esecuzione Localmente diff --git a/src/content/docs/ja/4x/guide/behind-proxies.mdx b/src/content/docs/ja/4x/guide/behind-proxies.mdx index 198dc59044..a70ee8bd1d 100644 --- a/src/content/docs/ja/4x/guide/behind-proxies.mdx +++ b/src/content/docs/ja/4x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ import Alert from '@components/primitives/Alert/Alert.astro'; リバースプロキシとして信頼する IP アドレス、サブネット、または IP アドレスとサブネットの配列。 次のリストに、事前に設定されたサブネット名が表示されます。 -* loopback - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniqueloc - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniqueloc - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` IPアドレスは以下のいずれかの方法で設定できます。 @@ -86,15 +86,17 @@ app.set('trust proxy', (ip) => {
    • - [req.hostname](/en/api#req.hostname) の値は、 - `X-Forwarded-Host` ヘッダで設定された値から取得されます。 クライアントやプロキシによって設定できます + [req.hostname](/en/api#req.hostname) の値は、 `X-Forwarded-Host` + ヘッダで設定された値から取得されます。 クライアントやプロキシによって設定できます
    • - `X-Forwarded-Proto` はリバースプロキシによって設定することで、アプリが https`か`http\` か無効な名前かをアプリに伝えることができます。 この値は [req.protocol](/en/api#req.protocol) で反映されます。 + `X-Forwarded-Proto` はリバースプロキシによって設定することで、アプリが https`か`http\` + か無効な名前かをアプリに伝えることができます。 この値は [req.protocol](/en/api#req.protocol) + で反映されます。
    • - [req.ip](/en/api#req.ip) と [req.ips](/en/api#req.ips) の値は、 - ソケットアドレスと `X-Forwarded-For` ヘッダーに基づいて入力されます。 最初の信頼されていないアドレスから始めます + [req.ip](/en/api#req.ip) と [req.ips](/en/api#req.ips) の値は、 ソケットアドレスと + `X-Forwarded-For` ヘッダーに基づいて入力されます。 最初の信頼されていないアドレスから始めます
    diff --git a/src/content/docs/ja/4x/guide/debugging.mdx b/src/content/docs/ja/4x/guide/debugging.mdx index 97edc6bd46..80cd35328f 100644 --- a/src/content/docs/ja/4x/guide/debugging.mdx +++ b/src/content/docs/ja/4x/guide/debugging.mdx @@ -106,12 +106,12 @@ $ DEBUG=http,mail,express:* node index.js Node.js を介して実行する場合、デバッグログの動作を変更するいくつかの環境変数を設定できます。 -| 名前 | 目的 | -| ------------------- | --------------------------- | -| `DEBUG` | 特定のデバッグ名前空間を有効/無効にします。 | -| `DEBUG_COLORS` | デバッグ出力で色を使用するかどうか。 | -| `DEBUG_DEPTH` | 物体検査の深さ。 | -| `DEBUG_FD` | デバッグ出力を書き込むファイル記述子。 | +| 名前 | 目的 | +| ------------------- | ------------------------------------------------------ | +| `DEBUG` | 特定のデバッグ名前空間を有効/無効にします。 | +| `DEBUG_COLORS` | デバッグ出力で色を使用するかどうか。 | +| `DEBUG_DEPTH` | 物体検査の深さ。 | +| `DEBUG_FD` | デバッグ出力を書き込むファイル記述子。 | | `DEBUG_SHOW_HIDDEN` | 検査対象オブジェクトに非表示のプロパティを表示します。 | diff --git a/src/content/docs/ja/4x/guide/error-handling.mdx b/src/content/docs/ja/4x/guide/error-handling.mdx index f0a21caaeb..4a19e9fcc1 100644 --- a/src/content/docs/ja/4x/guide/error-handling.mdx +++ b/src/content/docs/ja/4x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Express.jsが同期コードと非同期コードのエラーを処 import Alert from '@components/primitives/Alert/Alert.astro'; -_Error Handling_は、 +*Error Handling*は、 が同期と非同期の両方で発生するエラーをExpress がキャッチして処理する方法を指します。 Expressにはデフォルトのエラー ハンドラが付属しているので、始めるために自分で書く必要はありません。 @@ -161,12 +161,12 @@ written to the client with the stack trace. スタックトレースは本番環 エラーが書き込まれると、次の情報が 応答に追加されます: -* `res.statusCode` は `err.status` (または `err.statusCode`)から設定されます。 +- `res.statusCode` は `err.status` (または `err.statusCode`)から設定されます。 の場合、この値が4xxまたは5xxの範囲外の場合、500に設定されます。 -* `res.statusMessage` はステータスコードに従って設定されます。 -* 本文は、プロダクション +- `res.statusMessage` はステータスコードに従って設定されます。 +- 本文は、プロダクション 環境ではステータスコードメッセージのHTMLになります。そうでなければ、`err.stack`になります。 -* `err.headers` オブジェクトで指定されたヘッダー。 +- `err.headers` オブジェクトで指定されたヘッダー。 If you call `next()` with an error after you have started writing the response (for example, if you encounter an error while streaming the diff --git a/src/content/docs/ja/4x/guide/routing.mdx b/src/content/docs/ja/4x/guide/routing.mdx index e851b902c7..f2a8ebe75d 100644 --- a/src/content/docs/ja/4x/guide/routing.mdx +++ b/src/content/docs/ja/4x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Express.jsアプリケーションでルートを定義して使用 import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* とは、アプリケーションのエンドポイント(URI)がクライアントリクエストに対してどのように応答するかを指します。 +_Routing_ とは、アプリケーションのエンドポイント(URI)がクライアントリクエストに対してどのように応答するかを指します。 For an introduction to routing, see [Basic routing](/en/starter/basic-routing). HTTPメソッドに対応するExpress `app` オブジェクトのメソッドを使用してルーティングを定義します。 @@ -52,7 +52,7 @@ app.post('/', (req, res) => { Expressは、すべてのHTTPリクエストメソッドに対応するメソッドをサポートしています: `get`、`post`など。 完全なリストについては、 [app.METHOD](/en/5x/api#app.METHOD) を参照してください。 -特別なルーティングメソッド`app.all()`があり、_all_HTTPリクエストメソッドのパスにミドルウェア関数をロードするために使用されます。 例えば、`GET`を使用しているかどうかに関わらず、ルート`"/secret"へのリクエストに対して以下のハンドラが実行されます。 `POST`、`PUT`、`DELETE\`、または[http module](https://nodejs.org/api/http.html#http_http_methods)でサポートされている他のHTTPリクエストメソッド。 +特別なルーティングメソッド`app.all()`があり、\_all_HTTPリクエストメソッドのパスにミドルウェア関数をロードするために使用されます。 例えば、`GET`を使用しているかどうかに関わらず、ルート`"/secret"へのリクエストに対して以下のハンドラが実行されます。 `POST`、`PUT`、`DELETE\`、または[http module](https://nodejs.org/api/http.html#http_http_methods)でサポートされている他のHTTPリクエストメソッド。 ```js app.all('/secret', (req, res, next) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { この例では: -* `GET /user/5` → 最初のルートで処理 → "User 5" を送信 -* `GET /user/0` → 最初のroute ('route')`を呼び出し、次に一致する `/user/:id\` route (ルート) をスキップします。 +- `GET /user/5` → 最初のルートで処理 → "User 5" を送信 +- `GET /user/0` → 最初のroute ('route')`を呼び出し、次に一致する `/user/:id\` route (ルート) をスキップします。 ルートハンドラは、次の例に示すように、関数、関数の配列、または両方の組み合わせの形式で使用できます。 @@ -335,16 +335,16 @@ app.get( 次の表のレスポンスオブジェクト (`res`) のメソッドは、クライアントにレスポンスを送信し、リクエスト応答のサイクルを終了することができます。 これらのメソッドのいずれもルートハンドラから呼び出されない場合、クライアントリクエストはハングしたままになります。 -| 方法 | 説明 | -| --------------------------------------------- | ----------------------------------------- | -| [res.download()](/en/5x/api#res.download) | ダウンロードするファイルを指示します。 | -| [res.end()](/en/5x/api#res.end) | 応答プロセスを終了します。 | -| [res.json()](/en/5x/api#res.json) | JSON 応答を送信します。 | -| [res.jsonp()](/en/5x/api#res.jsonp) | JSONP サポートを使用して JSON 応答を送信します。 | -| [res.redirect()](/en/5x/api#res.redirect) | リダイレクトします。 | -| [res.render()](/en/5x/api#res.render) | ビューテンプレートをレンダリングします。 | -| [res.send()](/en/5x/api#res.send) | さまざまなタイプの応答を送信します。 | -| [res.sendFile()](/en/5x/api#res.sendFile) | ファイルをオクテットストリームとして送信する。 | +| 方法 | 説明 | +| --------------------------------------------- | ---------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | ダウンロードするファイルを指示します。 | +| [res.end()](/en/5x/api#res.end) | 応答プロセスを終了します。 | +| [res.json()](/en/5x/api#res.json) | JSON 応答を送信します。 | +| [res.jsonp()](/en/5x/api#res.jsonp) | JSONP サポートを使用して JSON 応答を送信します。 | +| [res.redirect()](/en/5x/api#res.redirect) | リダイレクトします。 | +| [res.render()](/en/5x/api#res.render) | ビューテンプレートをレンダリングします。 | +| [res.send()](/en/5x/api#res.send) | さまざまなタイプの応答を送信します。 | +| [res.sendFile()](/en/5x/api#res.sendFile) | ファイルをオクテットストリームとして送信する。 | | [res.sendStatus()](/en/5x/api#res.sendStatus) | レスポンスステータスコードを設定し、文字列表現をレスポンスボディとして送信します。 | ## app.route() diff --git a/src/content/docs/ja/4x/guide/using-middleware.mdx b/src/content/docs/ja/4x/guide/using-middleware.mdx index 352decfd81..18927c340c 100644 --- a/src/content/docs/ja/4x/guide/using-middleware.mdx +++ b/src/content/docs/ja/4x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express はルーティングおよびミドルウェアの Web フレームワークで、独自の最小限の機能を持っています。Express アプリケーションは、基本的にはミドルウェア関数の一連の呼び出しです。 -*Middleware* 関数は、[request object](/en/5x/api#req) (`req`) にアクセスできる関数です。 [response object](/en/5x/api#res) (`res`) と、アプリケーションのリクエストレスポンスサイクルの次のミドルウェア関数。 次のミドルウェア関数は通常`next`という名前の変数で表されます。 +_Middleware_ 関数は、[request object](/en/5x/api#req) (`req`) にアクセスできる関数です。 [response object](/en/5x/api#res) (`res`) と、アプリケーションのリクエストレスポンスサイクルの次のミドルウェア関数。 次のミドルウェア関数は通常`next`という名前の変数で表されます。 ミドルウェア機能は以下のタスクを実行できます。 -* 任意のコードを実行します。 -* リクエストとレスポンスオブジェクトに変更を加えます。 -* リクエストレスポンスサイクルを終了します。 -* スタック内の次のミドルウェア関数を呼び出します。 +- 任意のコードを実行します。 +- リクエストとレスポンスオブジェクトに変更を加えます。 +- リクエストレスポンスサイクルを終了します。 +- スタック内の次のミドルウェア関数を呼び出します。 現在のミドルウェア関数がリクエスト応答サイクルを終了しない場合は、次のミドルウェア関数に制御を渡すために `next()` を呼び出す必要があります。 そうでなければ、リクエストはハングアップのままになります。 Express アプリケーションでは、次のタイプのミドルウェアを使用できます。 -* [Application-level middleware](#middleware.application) -* [Router-level middleware](#middleware.router) -* [Error-handling middleware](#middleware.error-handling) -* [Built-in middleware](#middleware.built-in) -* [Third-party middleware](#middleware.third-party) +- [Application-level middleware](#middleware.application) +- [Router-level middleware](#middleware.router) +- [Error-handling middleware](#middleware.error-handling) +- [Built-in middleware](#middleware.built-in) +- [Third-party middleware](#middleware.third-party) アプリケーションレベルおよびルーターレベルのミドルウェアは、任意のマウントパスでロードできます。 また、一連のミドルウェア関数を一緒にロードして、マウントポイントでミドルウェアシステムのサブスタックを作成することもできます。 @@ -246,7 +246,7 @@ app.use('/admin', router, (req, res) => { -エラー処理ミドルウェアは常に_4つの引数を取ります。 エラー処理ミドルウェア関数として +エラー処理ミドルウェアは常に\_4つの引数を取ります。 エラー処理ミドルウェア関数として 識別するには、4つの引数を指定する必要があります。 `next` オブジェクトを使用しなくても、署名を維持するために指定する必要があります。 Otherwise, the `next` object will be interpreted as regular middleware and will fail to handle errors. @@ -271,9 +271,9 @@ functions that were previously included with Express are now in separate modules Express には次のミドルウェア関数が組み込まれています。 -* [express.static](/en/5x/api#express.static) は、HTML ファイル、画像などの静的なアセットを提供します。 -* [express.json](/en/5x/api#express.json) は、JSON ペイロードで受信したリクエストを解析します。 \*\*注意: Express 4.16.0+で利用可能 -* [express.urlencoded](/en/5x/api#express.urlencoded) は、URLエンコードされたペイロードで受信するリクエストを解析します。 \*\*注意: Express 4.16.0+で利用可能 +- [express.static](/en/5x/api#express.static) は、HTML ファイル、画像などの静的なアセットを提供します。 +- [express.json](/en/5x/api#express.json) は、JSON ペイロードで受信したリクエストを解析します。 \*\*注意: Express 4.16.0+で利用可能 +- [express.urlencoded](/en/5x/api#express.urlencoded) は、URLエンコードされたペイロードで受信するリクエストを解析します。 \*\*注意: Express 4.16.0+で利用可能 ## サードパーティのミドルウェア diff --git a/src/content/docs/ja/4x/guide/using-template-engines.mdx b/src/content/docs/ja/4x/guide/using-template-engines.mdx index 0403b69c27..acc079ae84 100644 --- a/src/content/docs/ja/4x/guide/using-template-engines.mdx +++ b/src/content/docs/ja/4x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Pug、Handlebars、EJSなどのテンプレートエンジンをExp import Alert from '@components/primitives/Alert/Alert.astro'; -*template engine* を使用すると、アプリケーションで静的なテンプレート ファイルを使用できます。 実行時に、テンプレートエンジンはテンプレートファイルの +_template engine_ を使用すると、アプリケーションで静的なテンプレート ファイルを使用できます。 実行時に、テンプレートエンジンはテンプレートファイルの 変数を実際の値に置き換えます。 をクリックして、テンプレートをクライアントに送信する HTML ファイルに変換します。 このアプローチにより、HTML ページのデザインが容易になります。 @@ -13,9 +13,9 @@ The [Express application generator](/en/starter/generator) uses [Pug](https://pu テンプレートファイルをレンダリングするには、ジェネレータが作成したデフォルトの `app.js` で、次の[アプリケーション設定プロパティ](/en/4x/api#app.set)を設定します。 -* `views` テンプレートファイルがあるディレクトリ。 例: `app.set('views', './views')` 。 +- `views` テンプレートファイルがあるディレクトリ。 例: `app.set('views', './views')` 。 デフォルトはアプリケーションのルートディレクトリにある `views` ディレクトリです。 -* `viewengine` を使用するテンプレートエンジン。 たとえば、Pugテンプレートエンジンを使用するには、`app.set('view engine', 'pug')`を使います。 +- `viewengine` を使用するテンプレートエンジン。 たとえば、Pugテンプレートエンジンを使用するには、`app.set('view engine', 'pug')`を使います。 次に、対応するテンプレートエンジン npm パッケージをインストールします。例えば、Pug をインストールする場合: diff --git a/src/content/docs/ja/4x/guide/writing-middleware.mdx b/src/content/docs/ja/4x/guide/writing-middleware.mdx index f6e9c71200..bc96db573c 100644 --- a/src/content/docs/ja/4x/guide/writing-middleware.mdx +++ b/src/content/docs/ja/4x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Express.jsアプリケーション用にカスタムミドルウェ import Alert from '@components/primitives/Alert/Alert.astro'; -*Middleware* 関数は、[request object](/en/5x/api#req) (`req`) にアクセスできる関数です。 [response object](/en/5x/api#res) (`res`)とアプリケーションのリクエストレスポンスサイクルの中の `next` 関数。 `next` 関数はExpressルータ内の関数で、呼び出されたときに現在のミドルウェアを継承してミドルウェアを実行します。 +_Middleware_ 関数は、[request object](/en/5x/api#req) (`req`) にアクセスできる関数です。 [response object](/en/5x/api#res) (`res`)とアプリケーションのリクエストレスポンスサイクルの中の `next` 関数。 `next` 関数はExpressルータ内の関数で、呼び出されたときに現在のミドルウェアを継承してミドルウェアを実行します。 ミドルウェア機能は以下のタスクを実行できます。 -* 任意のコードを実行します。 -* リクエストとレスポンスオブジェクトに変更を加えます。 -* リクエストレスポンスサイクルを終了します。 -* スタック内の次のミドルウェアを呼び出します。 +- 任意のコードを実行します。 +- リクエストとレスポンスオブジェクトに変更を加えます。 +- リクエストレスポンスサイクルを終了します。 +- スタック内の次のミドルウェアを呼び出します。 現在のミドルウェア関数がリクエスト応答サイクルを終了しない場合は、次のミドルウェア関数に制御を渡すために `next()` を呼び出す必要があります。 そうでなければ、リクエストはハングアップのままになります。 diff --git a/src/content/docs/ja/4x/starter/basic-routing.mdx b/src/content/docs/ja/4x/starter/basic-routing.mdx index f7e11efeca..a6e98519ec 100644 --- a/src/content/docs/ja/4x/starter/basic-routing.mdx +++ b/src/content/docs/ja/4x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Express.jsアプリケーションでルーティングの基礎を import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* は、アプリケーションが特定のエンドポイントに対してどのように応答するかを決定することを指します。 これはURI(またはパス)と特定のHTTPリクエストメソッド(GET、POSTなど)です。 +_Routing_ は、アプリケーションが特定のエンドポイントに対してどのように応答するかを決定することを指します。 これはURI(またはパス)と特定のHTTPリクエストメソッド(GET、POSTなど)です。 各ルートは、ルートが一致したときに実行される、1つまたは複数のハンドラ関数を持つことができます。 @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); 場所: -* `app` は `express` のインスタンスです。 -* `METHOD` は [HTTP リクエストメソッド](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods) の小文字です。 -* `PATH` はサーバー上のパスです。 -* `HANDLER` はルートが一致したときに実行される関数です。 +- `app` は `express` のインスタンスです。 +- `METHOD` は [HTTP リクエストメソッド](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods) の小文字です。 +- `PATH` はサーバー上のパスです。 +- `HANDLER` はルートが一致したときに実行される関数です。 diff --git a/src/content/docs/ja/4x/starter/examples.mdx b/src/content/docs/ja/4x/starter/examples.mdx index ec0da1a1fd..0c0be44268 100644 --- a/src/content/docs/ja/4x/starter/examples.mdx +++ b/src/content/docs/ja/4x/starter/examples.mdx @@ -5,31 +5,31 @@ description: さまざまなユースケース、インテグレーション、 import Alert from '@components/primitives/Alert/Alert.astro'; -* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - ログインとパスワードによる認証 -* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - HTTP コンテンツネゴシエーション -* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - クッキーベースのセッションの操作 -* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - クッキーの操作 -* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - クライアントへのファイルの転送 -* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - 埋め込みJavaScriptテンプレートの操作 (ejs) -* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - エラーページの作成 -* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - エラーミドルウェアの操作 -* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - シンプルなリクエストハンドラ。 -* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown as template engine. -* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - 複数のエクスプレスルーターでの作業 -* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - MVCスタイル コントローラ -* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - オンラインユーザーアクティビティを`オンライン`と`redis`パッケージで追跡 -* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - ルートパラメータの操作 -* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - 同じリソースに対する複数の HTTP 操作 -* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - 地図を使ってルートを整理する -* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - route middleware の操作 -* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - 各リソースごとにルートを整理する -* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Search API -* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - ユーザーセッション -* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - 静的ファイルの提供 -* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - 仮想ホストでの作業 -* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - ビューを動的にレンダリングする -* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - ミドルウェア呼び出し間でリクエストオブジェクトにデータを保存する -* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Simple API service +- [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - ログインとパスワードによる認証 +- [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - HTTP コンテンツネゴシエーション +- [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - クッキーベースのセッションの操作 +- [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - クッキーの操作 +- [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - クライアントへのファイルの転送 +- [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - 埋め込みJavaScriptテンプレートの操作 (ejs) +- [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - エラーページの作成 +- [error](https://github.com/expressjs/express/tree/4.x/examples/error) - エラーミドルウェアの操作 +- [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - シンプルなリクエストハンドラ。 +- [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown as template engine. +- [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - 複数のエクスプレスルーターでの作業 +- [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - MVCスタイル コントローラ +- [online](https://github.com/expressjs/express/tree/4.x/examples/online) - オンラインユーザーアクティビティを`オンライン`と`redis`パッケージで追跡 +- [params](https://github.com/expressjs/express/tree/4.x/examples/params) - ルートパラメータの操作 +- [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - 同じリソースに対する複数の HTTP 操作 +- [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - 地図を使ってルートを整理する +- [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - route middleware の操作 +- [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - 各リソースごとにルートを整理する +- [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Search API +- [session](https://github.com/expressjs/express/tree/4.x/examples/session) - ユーザーセッション +- [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - 静的ファイルの提供 +- [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - 仮想ホストでの作業 +- [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - ビューを動的にレンダリングする +- [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - ミドルウェア呼び出し間でリクエストオブジェクトにデータを保存する +- [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Simple API service ## その他の例 @@ -37,9 +37,9 @@ import Alert from '@components/primitives/Alert/Alert.astro'; この情報は、 - Expressjsチームがメンテナンスしていないサードパーティのサイト、製品、またはモジュールを指します。 ここでの掲載は、 - Expressjsプロジェクトチームの推奨または推奨を構成するものではありません。 + Expressjsチームがメンテナンスしていないサードパーティのサイト、製品、またはモジュールを指します。 + ここでの掲載は、 Expressjsプロジェクトチームの推奨または推奨を構成するものではありません。 -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - ORMとしてExpressとNext.jsを使用したフルスタックアプリ [Prisma](https://www.npmjs.com/package/prisma) -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - ORMとして [Prisma](https://www.npmjs.com/package/prisma) を使用する Express をTypeScript で REST API +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - ORMとしてExpressとNext.jsを使用したフルスタックアプリ [Prisma](https://www.npmjs.com/package/prisma) +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - ORMとして [Prisma](https://www.npmjs.com/package/prisma) を使用する Express をTypeScript で REST API diff --git a/src/content/docs/ja/4x/starter/generator.mdx b/src/content/docs/ja/4x/starter/generator.mdx index 308ecf85b6..13c433e806 100644 --- a/src/content/docs/ja/4x/starter/generator.mdx +++ b/src/content/docs/ja/4x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force force on non-empty directory ``` -例えば、次のように、*myapp* という名前の Express アプリケーションを作成します。 アプリは現在の作業ディレクトリの *myapp* というフォルダに作成され、ビューエンジンは Pug に設定されます。 +例えば、次のように、_myapp_ という名前の Express アプリケーションを作成します。 アプリは現在の作業ディレクトリの _myapp_ というフォルダに作成され、ビューエンジンは Pug に設定されます。 ```bash $ express --view=pug myapp diff --git a/src/content/docs/ja/4x/starter/hello-world.mdx b/src/content/docs/ja/4x/starter/hello-world.mdx index edc332e8bc..369821bf38 100644 --- a/src/content/docs/ja/4x/starter/hello-world.mdx +++ b/src/content/docs/ja/4x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; 以下に埋め込まれているのは、基本的に作成できる最も簡単なExpressアプリです。 It is a single file app -— *not* what you'd get if you use the [Express generator](/en/starter/generator), which +— _not_ what you'd get if you use the [Express generator](/en/starter/generator), which creates the scaffolding for a full app with numerous JavaScript files, Jade templates, and sub-directories for various purposes. @@ -28,7 +28,7 @@ app.listen(port, () => { }); ``` -このアプリはサーバーを起動し、接続のためにポート3000をリッスンします。 アプリはルート URL (`/`) または *route* にリクエスト +このアプリはサーバーを起動し、接続のためにポート3000をリッスンします。 アプリはルート URL (`/`) または _route_ にリクエスト を返します。 他のすべてのパスについては、**404 Not Found**で応答します。 ## ローカルで実行中 diff --git a/src/content/docs/ja/5x/guide/behind-proxies.mdx b/src/content/docs/ja/5x/guide/behind-proxies.mdx index 198dc59044..a70ee8bd1d 100644 --- a/src/content/docs/ja/5x/guide/behind-proxies.mdx +++ b/src/content/docs/ja/5x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ import Alert from '@components/primitives/Alert/Alert.astro'; リバースプロキシとして信頼する IP アドレス、サブネット、または IP アドレスとサブネットの配列。 次のリストに、事前に設定されたサブネット名が表示されます。 -* loopback - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniqueloc - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniqueloc - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` IPアドレスは以下のいずれかの方法で設定できます。 @@ -86,15 +86,17 @@ app.set('trust proxy', (ip) => {
    • - [req.hostname](/en/api#req.hostname) の値は、 - `X-Forwarded-Host` ヘッダで設定された値から取得されます。 クライアントやプロキシによって設定できます + [req.hostname](/en/api#req.hostname) の値は、 `X-Forwarded-Host` + ヘッダで設定された値から取得されます。 クライアントやプロキシによって設定できます
    • - `X-Forwarded-Proto` はリバースプロキシによって設定することで、アプリが https`か`http\` か無効な名前かをアプリに伝えることができます。 この値は [req.protocol](/en/api#req.protocol) で反映されます。 + `X-Forwarded-Proto` はリバースプロキシによって設定することで、アプリが https`か`http\` + か無効な名前かをアプリに伝えることができます。 この値は [req.protocol](/en/api#req.protocol) + で反映されます。
    • - [req.ip](/en/api#req.ip) と [req.ips](/en/api#req.ips) の値は、 - ソケットアドレスと `X-Forwarded-For` ヘッダーに基づいて入力されます。 最初の信頼されていないアドレスから始めます + [req.ip](/en/api#req.ip) と [req.ips](/en/api#req.ips) の値は、 ソケットアドレスと + `X-Forwarded-For` ヘッダーに基づいて入力されます。 最初の信頼されていないアドレスから始めます
    diff --git a/src/content/docs/ja/5x/guide/debugging.mdx b/src/content/docs/ja/5x/guide/debugging.mdx index 97edc6bd46..80cd35328f 100644 --- a/src/content/docs/ja/5x/guide/debugging.mdx +++ b/src/content/docs/ja/5x/guide/debugging.mdx @@ -106,12 +106,12 @@ $ DEBUG=http,mail,express:* node index.js Node.js を介して実行する場合、デバッグログの動作を変更するいくつかの環境変数を設定できます。 -| 名前 | 目的 | -| ------------------- | --------------------------- | -| `DEBUG` | 特定のデバッグ名前空間を有効/無効にします。 | -| `DEBUG_COLORS` | デバッグ出力で色を使用するかどうか。 | -| `DEBUG_DEPTH` | 物体検査の深さ。 | -| `DEBUG_FD` | デバッグ出力を書き込むファイル記述子。 | +| 名前 | 目的 | +| ------------------- | ------------------------------------------------------ | +| `DEBUG` | 特定のデバッグ名前空間を有効/無効にします。 | +| `DEBUG_COLORS` | デバッグ出力で色を使用するかどうか。 | +| `DEBUG_DEPTH` | 物体検査の深さ。 | +| `DEBUG_FD` | デバッグ出力を書き込むファイル記述子。 | | `DEBUG_SHOW_HIDDEN` | 検査対象オブジェクトに非表示のプロパティを表示します。 | diff --git a/src/content/docs/ja/5x/guide/error-handling.mdx b/src/content/docs/ja/5x/guide/error-handling.mdx index f0a21caaeb..4a19e9fcc1 100644 --- a/src/content/docs/ja/5x/guide/error-handling.mdx +++ b/src/content/docs/ja/5x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Express.jsが同期コードと非同期コードのエラーを処 import Alert from '@components/primitives/Alert/Alert.astro'; -_Error Handling_は、 +*Error Handling*は、 が同期と非同期の両方で発生するエラーをExpress がキャッチして処理する方法を指します。 Expressにはデフォルトのエラー ハンドラが付属しているので、始めるために自分で書く必要はありません。 @@ -161,12 +161,12 @@ written to the client with the stack trace. スタックトレースは本番環 エラーが書き込まれると、次の情報が 応答に追加されます: -* `res.statusCode` は `err.status` (または `err.statusCode`)から設定されます。 +- `res.statusCode` は `err.status` (または `err.statusCode`)から設定されます。 の場合、この値が4xxまたは5xxの範囲外の場合、500に設定されます。 -* `res.statusMessage` はステータスコードに従って設定されます。 -* 本文は、プロダクション +- `res.statusMessage` はステータスコードに従って設定されます。 +- 本文は、プロダクション 環境ではステータスコードメッセージのHTMLになります。そうでなければ、`err.stack`になります。 -* `err.headers` オブジェクトで指定されたヘッダー。 +- `err.headers` オブジェクトで指定されたヘッダー。 If you call `next()` with an error after you have started writing the response (for example, if you encounter an error while streaming the diff --git a/src/content/docs/ja/5x/guide/routing.mdx b/src/content/docs/ja/5x/guide/routing.mdx index e851b902c7..f2a8ebe75d 100644 --- a/src/content/docs/ja/5x/guide/routing.mdx +++ b/src/content/docs/ja/5x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Express.jsアプリケーションでルートを定義して使用 import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* とは、アプリケーションのエンドポイント(URI)がクライアントリクエストに対してどのように応答するかを指します。 +_Routing_ とは、アプリケーションのエンドポイント(URI)がクライアントリクエストに対してどのように応答するかを指します。 For an introduction to routing, see [Basic routing](/en/starter/basic-routing). HTTPメソッドに対応するExpress `app` オブジェクトのメソッドを使用してルーティングを定義します。 @@ -52,7 +52,7 @@ app.post('/', (req, res) => { Expressは、すべてのHTTPリクエストメソッドに対応するメソッドをサポートしています: `get`、`post`など。 完全なリストについては、 [app.METHOD](/en/5x/api#app.METHOD) を参照してください。 -特別なルーティングメソッド`app.all()`があり、_all_HTTPリクエストメソッドのパスにミドルウェア関数をロードするために使用されます。 例えば、`GET`を使用しているかどうかに関わらず、ルート`"/secret"へのリクエストに対して以下のハンドラが実行されます。 `POST`、`PUT`、`DELETE\`、または[http module](https://nodejs.org/api/http.html#http_http_methods)でサポートされている他のHTTPリクエストメソッド。 +特別なルーティングメソッド`app.all()`があり、\_all_HTTPリクエストメソッドのパスにミドルウェア関数をロードするために使用されます。 例えば、`GET`を使用しているかどうかに関わらず、ルート`"/secret"へのリクエストに対して以下のハンドラが実行されます。 `POST`、`PUT`、`DELETE\`、または[http module](https://nodejs.org/api/http.html#http_http_methods)でサポートされている他のHTTPリクエストメソッド。 ```js app.all('/secret', (req, res, next) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { この例では: -* `GET /user/5` → 最初のルートで処理 → "User 5" を送信 -* `GET /user/0` → 最初のroute ('route')`を呼び出し、次に一致する `/user/:id\` route (ルート) をスキップします。 +- `GET /user/5` → 最初のルートで処理 → "User 5" を送信 +- `GET /user/0` → 最初のroute ('route')`を呼び出し、次に一致する `/user/:id\` route (ルート) をスキップします。 ルートハンドラは、次の例に示すように、関数、関数の配列、または両方の組み合わせの形式で使用できます。 @@ -335,16 +335,16 @@ app.get( 次の表のレスポンスオブジェクト (`res`) のメソッドは、クライアントにレスポンスを送信し、リクエスト応答のサイクルを終了することができます。 これらのメソッドのいずれもルートハンドラから呼び出されない場合、クライアントリクエストはハングしたままになります。 -| 方法 | 説明 | -| --------------------------------------------- | ----------------------------------------- | -| [res.download()](/en/5x/api#res.download) | ダウンロードするファイルを指示します。 | -| [res.end()](/en/5x/api#res.end) | 応答プロセスを終了します。 | -| [res.json()](/en/5x/api#res.json) | JSON 応答を送信します。 | -| [res.jsonp()](/en/5x/api#res.jsonp) | JSONP サポートを使用して JSON 応答を送信します。 | -| [res.redirect()](/en/5x/api#res.redirect) | リダイレクトします。 | -| [res.render()](/en/5x/api#res.render) | ビューテンプレートをレンダリングします。 | -| [res.send()](/en/5x/api#res.send) | さまざまなタイプの応答を送信します。 | -| [res.sendFile()](/en/5x/api#res.sendFile) | ファイルをオクテットストリームとして送信する。 | +| 方法 | 説明 | +| --------------------------------------------- | ---------------------------------------------------------------------------------- | +| [res.download()](/en/5x/api#res.download) | ダウンロードするファイルを指示します。 | +| [res.end()](/en/5x/api#res.end) | 応答プロセスを終了します。 | +| [res.json()](/en/5x/api#res.json) | JSON 応答を送信します。 | +| [res.jsonp()](/en/5x/api#res.jsonp) | JSONP サポートを使用して JSON 応答を送信します。 | +| [res.redirect()](/en/5x/api#res.redirect) | リダイレクトします。 | +| [res.render()](/en/5x/api#res.render) | ビューテンプレートをレンダリングします。 | +| [res.send()](/en/5x/api#res.send) | さまざまなタイプの応答を送信します。 | +| [res.sendFile()](/en/5x/api#res.sendFile) | ファイルをオクテットストリームとして送信する。 | | [res.sendStatus()](/en/5x/api#res.sendStatus) | レスポンスステータスコードを設定し、文字列表現をレスポンスボディとして送信します。 | ## app.route() diff --git a/src/content/docs/ja/5x/guide/using-middleware.mdx b/src/content/docs/ja/5x/guide/using-middleware.mdx index 352decfd81..18927c340c 100644 --- a/src/content/docs/ja/5x/guide/using-middleware.mdx +++ b/src/content/docs/ja/5x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express はルーティングおよびミドルウェアの Web フレームワークで、独自の最小限の機能を持っています。Express アプリケーションは、基本的にはミドルウェア関数の一連の呼び出しです。 -*Middleware* 関数は、[request object](/en/5x/api#req) (`req`) にアクセスできる関数です。 [response object](/en/5x/api#res) (`res`) と、アプリケーションのリクエストレスポンスサイクルの次のミドルウェア関数。 次のミドルウェア関数は通常`next`という名前の変数で表されます。 +_Middleware_ 関数は、[request object](/en/5x/api#req) (`req`) にアクセスできる関数です。 [response object](/en/5x/api#res) (`res`) と、アプリケーションのリクエストレスポンスサイクルの次のミドルウェア関数。 次のミドルウェア関数は通常`next`という名前の変数で表されます。 ミドルウェア機能は以下のタスクを実行できます。 -* 任意のコードを実行します。 -* リクエストとレスポンスオブジェクトに変更を加えます。 -* リクエストレスポンスサイクルを終了します。 -* スタック内の次のミドルウェア関数を呼び出します。 +- 任意のコードを実行します。 +- リクエストとレスポンスオブジェクトに変更を加えます。 +- リクエストレスポンスサイクルを終了します。 +- スタック内の次のミドルウェア関数を呼び出します。 現在のミドルウェア関数がリクエスト応答サイクルを終了しない場合は、次のミドルウェア関数に制御を渡すために `next()` を呼び出す必要があります。 そうでなければ、リクエストはハングアップのままになります。 Express アプリケーションでは、次のタイプのミドルウェアを使用できます。 -* [Application-level middleware](#middleware.application) -* [Router-level middleware](#middleware.router) -* [Error-handling middleware](#middleware.error-handling) -* [Built-in middleware](#middleware.built-in) -* [Third-party middleware](#middleware.third-party) +- [Application-level middleware](#middleware.application) +- [Router-level middleware](#middleware.router) +- [Error-handling middleware](#middleware.error-handling) +- [Built-in middleware](#middleware.built-in) +- [Third-party middleware](#middleware.third-party) アプリケーションレベルおよびルーターレベルのミドルウェアは、任意のマウントパスでロードできます。 また、一連のミドルウェア関数を一緒にロードして、マウントポイントでミドルウェアシステムのサブスタックを作成することもできます。 @@ -246,7 +246,7 @@ app.use('/admin', router, (req, res) => { -エラー処理ミドルウェアは常に_4つの引数を取ります。 エラー処理ミドルウェア関数として +エラー処理ミドルウェアは常に\_4つの引数を取ります。 エラー処理ミドルウェア関数として 識別するには、4つの引数を指定する必要があります。 `next` オブジェクトを使用しなくても、署名を維持するために指定する必要があります。 Otherwise, the `next` object will be interpreted as regular middleware and will fail to handle errors. @@ -271,9 +271,9 @@ functions that were previously included with Express are now in separate modules Express には次のミドルウェア関数が組み込まれています。 -* [express.static](/en/5x/api#express.static) は、HTML ファイル、画像などの静的なアセットを提供します。 -* [express.json](/en/5x/api#express.json) は、JSON ペイロードで受信したリクエストを解析します。 \*\*注意: Express 4.16.0+で利用可能 -* [express.urlencoded](/en/5x/api#express.urlencoded) は、URLエンコードされたペイロードで受信するリクエストを解析します。 \*\*注意: Express 4.16.0+で利用可能 +- [express.static](/en/5x/api#express.static) は、HTML ファイル、画像などの静的なアセットを提供します。 +- [express.json](/en/5x/api#express.json) は、JSON ペイロードで受信したリクエストを解析します。 \*\*注意: Express 4.16.0+で利用可能 +- [express.urlencoded](/en/5x/api#express.urlencoded) は、URLエンコードされたペイロードで受信するリクエストを解析します。 \*\*注意: Express 4.16.0+で利用可能 ## サードパーティのミドルウェア diff --git a/src/content/docs/ja/5x/guide/using-template-engines.mdx b/src/content/docs/ja/5x/guide/using-template-engines.mdx index 0403b69c27..acc079ae84 100644 --- a/src/content/docs/ja/5x/guide/using-template-engines.mdx +++ b/src/content/docs/ja/5x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Pug、Handlebars、EJSなどのテンプレートエンジンをExp import Alert from '@components/primitives/Alert/Alert.astro'; -*template engine* を使用すると、アプリケーションで静的なテンプレート ファイルを使用できます。 実行時に、テンプレートエンジンはテンプレートファイルの +_template engine_ を使用すると、アプリケーションで静的なテンプレート ファイルを使用できます。 実行時に、テンプレートエンジンはテンプレートファイルの 変数を実際の値に置き換えます。 をクリックして、テンプレートをクライアントに送信する HTML ファイルに変換します。 このアプローチにより、HTML ページのデザインが容易になります。 @@ -13,9 +13,9 @@ The [Express application generator](/en/starter/generator) uses [Pug](https://pu テンプレートファイルをレンダリングするには、ジェネレータが作成したデフォルトの `app.js` で、次の[アプリケーション設定プロパティ](/en/4x/api#app.set)を設定します。 -* `views` テンプレートファイルがあるディレクトリ。 例: `app.set('views', './views')` 。 +- `views` テンプレートファイルがあるディレクトリ。 例: `app.set('views', './views')` 。 デフォルトはアプリケーションのルートディレクトリにある `views` ディレクトリです。 -* `viewengine` を使用するテンプレートエンジン。 たとえば、Pugテンプレートエンジンを使用するには、`app.set('view engine', 'pug')`を使います。 +- `viewengine` を使用するテンプレートエンジン。 たとえば、Pugテンプレートエンジンを使用するには、`app.set('view engine', 'pug')`を使います。 次に、対応するテンプレートエンジン npm パッケージをインストールします。例えば、Pug をインストールする場合: diff --git a/src/content/docs/ja/5x/guide/writing-middleware.mdx b/src/content/docs/ja/5x/guide/writing-middleware.mdx index 87747e65b1..22e7a1f6d3 100644 --- a/src/content/docs/ja/5x/guide/writing-middleware.mdx +++ b/src/content/docs/ja/5x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Express.jsアプリケーション用にカスタムミドルウェ import Alert from '@components/primitives/Alert/Alert.astro'; -*Middleware* 関数は、[request object](/en/5x/api#req) (`req`) にアクセスできる関数です。 [response object](/en/5x/api#res) (`res`)とアプリケーションのリクエストレスポンスサイクルの中の `next` 関数。 `next` 関数はExpressルータ内の関数で、呼び出されたときに現在のミドルウェアを継承してミドルウェアを実行します。 +_Middleware_ 関数は、[request object](/en/5x/api#req) (`req`) にアクセスできる関数です。 [response object](/en/5x/api#res) (`res`)とアプリケーションのリクエストレスポンスサイクルの中の `next` 関数。 `next` 関数はExpressルータ内の関数で、呼び出されたときに現在のミドルウェアを継承してミドルウェアを実行します。 ミドルウェア機能は以下のタスクを実行できます。 -* 任意のコードを実行します。 -* リクエストとレスポンスオブジェクトに変更を加えます。 -* リクエストレスポンスサイクルを終了します。 -* スタック内の次のミドルウェアを呼び出します。 +- 任意のコードを実行します。 +- リクエストとレスポンスオブジェクトに変更を加えます。 +- リクエストレスポンスサイクルを終了します。 +- スタック内の次のミドルウェアを呼び出します。 現在のミドルウェア関数がリクエスト応答サイクルを終了しない場合は、次のミドルウェア関数に制御を渡すために `next()` を呼び出す必要があります。 そうでなければ、リクエストはハングアップのままになります。 diff --git a/src/content/docs/ja/5x/starter/basic-routing.mdx b/src/content/docs/ja/5x/starter/basic-routing.mdx index f7e11efeca..a6e98519ec 100644 --- a/src/content/docs/ja/5x/starter/basic-routing.mdx +++ b/src/content/docs/ja/5x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Express.jsアプリケーションでルーティングの基礎を import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* は、アプリケーションが特定のエンドポイントに対してどのように応答するかを決定することを指します。 これはURI(またはパス)と特定のHTTPリクエストメソッド(GET、POSTなど)です。 +_Routing_ は、アプリケーションが特定のエンドポイントに対してどのように応答するかを決定することを指します。 これはURI(またはパス)と特定のHTTPリクエストメソッド(GET、POSTなど)です。 各ルートは、ルートが一致したときに実行される、1つまたは複数のハンドラ関数を持つことができます。 @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); 場所: -* `app` は `express` のインスタンスです。 -* `METHOD` は [HTTP リクエストメソッド](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods) の小文字です。 -* `PATH` はサーバー上のパスです。 -* `HANDLER` はルートが一致したときに実行される関数です。 +- `app` は `express` のインスタンスです。 +- `METHOD` は [HTTP リクエストメソッド](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods) の小文字です。 +- `PATH` はサーバー上のパスです。 +- `HANDLER` はルートが一致したときに実行される関数です。 diff --git a/src/content/docs/ja/5x/starter/examples.mdx b/src/content/docs/ja/5x/starter/examples.mdx index c85510841e..f95e9eeba1 100644 --- a/src/content/docs/ja/5x/starter/examples.mdx +++ b/src/content/docs/ja/5x/starter/examples.mdx @@ -7,31 +7,31 @@ import Alert from '@components/primitives/Alert/Alert.astro'; このページには、Express を使用した例のリストがあります。 -* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - ログインとパスワードによる認証 -* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - HTTP コンテンツネゴシエーション -* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - クッキーベースのセッションの操作 -* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - クッキーの操作 -* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - クライアントへのファイルの転送 -* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - 埋め込みJavaScriptテンプレートの操作 (ejs) -* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - エラーページの作成 -* [error](https://github.com/expressjs/express/tree/master/examples/error) - エラーミドルウェアの操作 -* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - シンプルなリクエストハンドラ。 -* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown as template engine. -* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - 複数のエクスプレスルーターでの作業 -* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - MVCスタイル コントローラ -* [online](https://github.com/expressjs/express/tree/master/examples/online) - オンラインユーザーアクティビティを`オンライン`と`redis`パッケージで追跡 -* [params](https://github.com/expressjs/express/tree/master/examples/params) - ルートパラメータの操作 -* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - 同じリソースに対する複数の HTTP 操作 -* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - 地図を使ってルートを整理する -* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - route middleware の操作 -* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - 各リソースごとにルートを整理する -* [search](https://github.com/expressjs/express/tree/master/examples/search) - Search API -* [session](https://github.com/expressjs/express/tree/master/examples/session) - ユーザーセッション -* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - 静的ファイルの提供 -* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - 仮想ホストでの作業 -* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - ビューを動的にレンダリングする -* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - ミドルウェア呼び出し間でリクエストオブジェクトにデータを保存する -* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Simple API service +- [auth](https://github.com/expressjs/express/tree/master/examples/auth) - ログインとパスワードによる認証 +- [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - HTTP コンテンツネゴシエーション +- [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - クッキーベースのセッションの操作 +- [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - クッキーの操作 +- [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - クライアントへのファイルの転送 +- [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - 埋め込みJavaScriptテンプレートの操作 (ejs) +- [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - エラーページの作成 +- [error](https://github.com/expressjs/express/tree/master/examples/error) - エラーミドルウェアの操作 +- [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - シンプルなリクエストハンドラ。 +- [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown as template engine. +- [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - 複数のエクスプレスルーターでの作業 +- [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - MVCスタイル コントローラ +- [online](https://github.com/expressjs/express/tree/master/examples/online) - オンラインユーザーアクティビティを`オンライン`と`redis`パッケージで追跡 +- [params](https://github.com/expressjs/express/tree/master/examples/params) - ルートパラメータの操作 +- [resource](https://github.com/expressjs/express/tree/master/examples/resource) - 同じリソースに対する複数の HTTP 操作 +- [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - 地図を使ってルートを整理する +- [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - route middleware の操作 +- [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - 各リソースごとにルートを整理する +- [search](https://github.com/expressjs/express/tree/master/examples/search) - Search API +- [session](https://github.com/expressjs/express/tree/master/examples/session) - ユーザーセッション +- [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - 静的ファイルの提供 +- [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - 仮想ホストでの作業 +- [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - ビューを動的にレンダリングする +- [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - ミドルウェア呼び出し間でリクエストオブジェクトにデータを保存する +- [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Simple API service ## その他の例 @@ -45,5 +45,5 @@ Expressjsプロジェクトチームの推奨または推奨を構成するも -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - ORMとしてExpressとNext.jsを使用したフルスタックアプリ [Prisma](https://www.npmjs.com/package/prisma) -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - ORMとして [Prisma](https://www.npmjs.com/package/prisma) を使用する Express をTypeScript で REST API +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - ORMとしてExpressとNext.jsを使用したフルスタックアプリ [Prisma](https://www.npmjs.com/package/prisma) +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - ORMとして [Prisma](https://www.npmjs.com/package/prisma) を使用する Express をTypeScript で REST API diff --git a/src/content/docs/ja/5x/starter/generator.mdx b/src/content/docs/ja/5x/starter/generator.mdx index 308ecf85b6..13c433e806 100644 --- a/src/content/docs/ja/5x/starter/generator.mdx +++ b/src/content/docs/ja/5x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force force on non-empty directory ``` -例えば、次のように、*myapp* という名前の Express アプリケーションを作成します。 アプリは現在の作業ディレクトリの *myapp* というフォルダに作成され、ビューエンジンは Pug に設定されます。 +例えば、次のように、_myapp_ という名前の Express アプリケーションを作成します。 アプリは現在の作業ディレクトリの _myapp_ というフォルダに作成され、ビューエンジンは Pug に設定されます。 ```bash $ express --view=pug myapp diff --git a/src/content/docs/ja/5x/starter/hello-world.mdx b/src/content/docs/ja/5x/starter/hello-world.mdx index edc332e8bc..369821bf38 100644 --- a/src/content/docs/ja/5x/starter/hello-world.mdx +++ b/src/content/docs/ja/5x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; 以下に埋め込まれているのは、基本的に作成できる最も簡単なExpressアプリです。 It is a single file app -— *not* what you'd get if you use the [Express generator](/en/starter/generator), which +— _not_ what you'd get if you use the [Express generator](/en/starter/generator), which creates the scaffolding for a full app with numerous JavaScript files, Jade templates, and sub-directories for various purposes. @@ -28,7 +28,7 @@ app.listen(port, () => { }); ``` -このアプリはサーバーを起動し、接続のためにポート3000をリッスンします。 アプリはルート URL (`/`) または *route* にリクエスト +このアプリはサーバーを起動し、接続のためにポート3000をリッスンします。 アプリはルート URL (`/`) または _route_ にリクエスト を返します。 他のすべてのパスについては、**404 Not Found**で応答します。 ## ローカルで実行中 diff --git a/src/content/docs/ko/4x/guide/behind-proxies.mdx b/src/content/docs/ko/4x/guide/behind-proxies.mdx index dc509998f7..d96970dd67 100644 --- a/src/content/docs/ko/4x/guide/behind-proxies.mdx +++ b/src/content/docs/ko/4x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ When setting to `true`, it is important to ensure that the last reverse proxy tr An IP address, subnet, or an array of IP addresses and subnets to trust as being a reverse proxy. The following list shows the pre-configured subnet names: -* loopback - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` You can set IP addresses in any of the following ways: diff --git a/src/content/docs/ko/4x/guide/error-handling.mdx b/src/content/docs/ko/4x/guide/error-handling.mdx index 78f1c86e92..e34218f841 100644 --- a/src/content/docs/ko/4x/guide/error-handling.mdx +++ b/src/content/docs/ko/4x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Understand how Express.js handles errors in synchronous and asynchr import Alert from '@components/primitives/Alert/Alert.astro'; -*Error Handling* refers to how Express catches and processes errors that +_Error Handling_ refers to how Express catches and processes errors that occur both synchronously and asynchronously. Express comes with a default error handler so you don't need to write your own to get started. @@ -161,12 +161,12 @@ Set the environment variable `NODE_ENV` to `production`, to run the app in produ When an error is written, the following information is added to the response: -* The `res.statusCode` is set from `err.status` (or `err.statusCode`). If +- The `res.statusCode` is set from `err.status` (or `err.statusCode`). If this value is outside the 4xx or 5xx range, it will be set to 500. -* The `res.statusMessage` is set according to the status code. -* The body will be the HTML of the status code message when in production +- The `res.statusMessage` is set according to the status code. +- The body will be the HTML of the status code message when in production environment, otherwise will be `err.stack`. -* Any headers specified in an `err.headers` object. +- Any headers specified in an `err.headers` object. If you call `next()` with an error after you have started writing the response (for example, if you encounter an error while streaming the @@ -258,7 +258,7 @@ function logErrors(err, req, res, next) { Also in this example, `clientErrorHandler` is defined as follows; in this case, the error is explicitly passed along to the next one. -Notice that when *not* calling "next" in an error-handling function, you are responsible for writing (and ending) the response. Otherwise, those requests will "hang" and will not be eligible for garbage collection. +Notice that when _not_ calling "next" in an error-handling function, you are responsible for writing (and ending) the response. Otherwise, those requests will "hang" and will not be eligible for garbage collection. ```js function clientErrorHandler(err, req, res, next) { diff --git a/src/content/docs/ko/4x/guide/routing.mdx b/src/content/docs/ko/4x/guide/routing.mdx index 78ab64f6e8..930e7b8438 100644 --- a/src/content/docs/ko/4x/guide/routing.mdx +++ b/src/content/docs/ko/4x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Learn how to define and use routes in Express.js applications, incl import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* refers to how an application's endpoints (URIs) respond to client requests. +_Routing_ refers to how an application's endpoints (URIs) respond to client requests. For an introduction to routing, see [Basic routing](/en/starter/basic-routing). You define routing using methods of the Express `app` object that correspond to HTTP methods; @@ -52,7 +52,7 @@ app.post('/', (req, res) => { Express supports methods that correspond to all HTTP request methods: `get`, `post`, and so on. For a full list, see [app.METHOD](/en/5x/api#app.METHOD). -There is a special routing method, `app.all()`, used to load middleware functions at a path for *all* HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). +There is a special routing method, `app.all()`, used to load middleware functions at a path for _all_ HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { In this example: -* `GET /user/5` → handled by first route → sends "User 5" -* `GET /user/0` → first route calls `next('route')`, skipping to the next matching `/user/:id` route +- `GET /user/5` → handled by first route → sends "User 5" +- `GET /user/0` → first route calls `next('route')`, skipping to the next matching `/user/:id` route Route handlers can be in the form of a function, an array of functions, or combinations of both, as shown in the following examples. diff --git a/src/content/docs/ko/4x/guide/using-middleware.mdx b/src/content/docs/ko/4x/guide/using-middleware.mdx index 026542a234..36f8034ef2 100644 --- a/src/content/docs/ko/4x/guide/using-middleware.mdx +++ b/src/content/docs/ko/4x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express is a routing and middleware web framework that has minimal functionality of its own: An Express application is essentially a series of middleware function calls. -*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. +_Middleware_ functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. Middleware functions can perform the following tasks: -* Execute any code. -* Make changes to the request and the response objects. -* End the request-response cycle. -* Call the next middleware function in the stack. +- Execute any code. +- Make changes to the request and the response objects. +- End the request-response cycle. +- Call the next middleware function in the stack. If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. An Express application can use the following types of middleware: -* [Application-level middleware](#middleware.application) -* [Router-level middleware](#middleware.router) -* [Error-handling middleware](#middleware.error-handling) -* [Built-in middleware](#middleware.built-in) -* [Third-party middleware](#middleware.third-party) +- [Application-level middleware](#middleware.application) +- [Router-level middleware](#middleware.router) +- [Error-handling middleware](#middleware.error-handling) +- [Built-in middleware](#middleware.built-in) +- [Third-party middleware](#middleware.third-party) You can load application-level and router-level middleware with an optional mount path. You can also load a series of middleware functions together, which creates a sub-stack of the middleware system at a mount point. @@ -246,7 +246,7 @@ app.use('/admin', router, (req, res) => { -Error-handling middleware always takes *four* arguments. You must provide four arguments to +Error-handling middleware always takes _four_ arguments. You must provide four arguments to identify it as an error-handling middleware function. Even if you don't need to use the `next` object, you must specify it to maintain the signature. Otherwise, the `next` object will be interpreted as regular middleware and will fail to handle errors. @@ -271,9 +271,9 @@ functions that were previously included with Express are now in separate modules Express has the following built-in middleware functions: -* [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. -* [express.json](/en/5x/api#express.json) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** +- [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. +- [express.json](/en/5x/api#express.json) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** ## Third-party middleware diff --git a/src/content/docs/ko/4x/guide/using-template-engines.mdx b/src/content/docs/ko/4x/guide/using-template-engines.mdx index 7095bc6dd5..31edcdde82 100644 --- a/src/content/docs/ko/4x/guide/using-template-engines.mdx +++ b/src/content/docs/ko/4x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Discover how to integrate and use template engines like Pug, Handle import Alert from '@components/primitives/Alert/Alert.astro'; -A *template engine* enables you to use static template files in your application. At runtime, the template engine replaces +A _template engine_ enables you to use static template files in your application. At runtime, the template engine replaces variables in a template file with actual values, and transforms the template into an HTML file sent to the client. This approach makes it easier to design an HTML page. @@ -13,9 +13,9 @@ The [Express application generator](/en/starter/generator) uses [Pug](https://pu To render template files, set the following [application setting properties](/en/4x/api#app.set), in the default `app.js` created by the generator: -* `views`, the directory where the template files are located. Eg: `app.set('views', './views')`. +- `views`, the directory where the template files are located. Eg: `app.set('views', './views')`. This defaults to the `views` directory in the application root directory. -* `view engine`, the template engine to use. For example, to use the Pug template engine: `app.set('view engine', 'pug')`. +- `view engine`, the template engine to use. For example, to use the Pug template engine: `app.set('view engine', 'pug')`. Then install the corresponding template engine npm package; for example to install Pug: diff --git a/src/content/docs/ko/4x/guide/writing-middleware.mdx b/src/content/docs/ko/4x/guide/writing-middleware.mdx index 355028e8b0..3849cfe1fa 100644 --- a/src/content/docs/ko/4x/guide/writing-middleware.mdx +++ b/src/content/docs/ko/4x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Learn how to write custom middleware functions for Express.js appli import Alert from '@components/primitives/Alert/Alert.astro'; -*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. +_Middleware_ functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. Middleware functions can perform the following tasks: -* Execute any code. -* Make changes to the request and the response objects. -* End the request-response cycle. -* Call the next middleware in the stack. +- Execute any code. +- Make changes to the request and the response objects. +- End the request-response cycle. +- Call the next middleware in the stack. If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. diff --git a/src/content/docs/ko/4x/starter/basic-routing.mdx b/src/content/docs/ko/4x/starter/basic-routing.mdx index 35d674808b..73c12f3893 100644 --- a/src/content/docs/ko/4x/starter/basic-routing.mdx +++ b/src/content/docs/ko/4x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Learn the fundamentals of routing in Express.js applications, inclu import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). +_Routing_ refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). Each route can have one or more handler functions, which are executed when the route is matched. @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); Where: -* `app` is an instance of `express`. -* `METHOD` is an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in lowercase. -* `PATH` is a path on the server. -* `HANDLER` is the function executed when the route is matched. +- `app` is an instance of `express`. +- `METHOD` is an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in lowercase. +- `PATH` is a path on the server. +- `HANDLER` is the function executed when the route is matched. diff --git a/src/content/docs/ko/4x/starter/examples.mdx b/src/content/docs/ko/4x/starter/examples.mdx index 4135b751cd..6685b9cbe4 100644 --- a/src/content/docs/ko/4x/starter/examples.mdx +++ b/src/content/docs/ko/4x/starter/examples.mdx @@ -5,31 +5,31 @@ description: Explore a collection of Express.js application examples covering va import Alert from '@components/primitives/Alert/Alert.astro'; -* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Authentication with login and password -* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - HTTP content negotiation -* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Working with cookie-based sessions -* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Working with cookies -* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transferring files to client -* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Working with Embedded JavaScript templating (ejs) -* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Creating error pages -* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Working with error middleware -* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Simple request handler -* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown as template engine -* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Working with multiple Express routers -* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - MVC-style controllers -* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Tracking online user activity with `online` and `redis` packages -* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Working with route parameters -* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Multiple HTTP operations on the same resource -* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organizing routes using a map -* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Working with route middleware -* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizing routes per each resource -* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Search API -* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - User sessions -* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Serving static files -* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Working with virtual hosts -* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Rendering views dynamically -* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Saving data in request object between middleware calls -* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Simple API service +- [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Authentication with login and password +- [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - HTTP content negotiation +- [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Working with cookie-based sessions +- [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Working with cookies +- [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transferring files to client +- [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Working with Embedded JavaScript templating (ejs) +- [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Creating error pages +- [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Working with error middleware +- [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Simple request handler +- [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown as template engine +- [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Working with multiple Express routers +- [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - MVC-style controllers +- [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Tracking online user activity with `online` and `redis` packages +- [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Working with route parameters +- [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Multiple HTTP operations on the same resource +- [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organizing routes using a map +- [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Working with route middleware +- [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizing routes per each resource +- [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Search API +- [session](https://github.com/expressjs/express/tree/4.x/examples/session) - User sessions +- [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Serving static files +- [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Working with virtual hosts +- [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Rendering views dynamically +- [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Saving data in request object between middleware calls +- [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Simple API service ## Additional examples @@ -41,5 +41,5 @@ These are some additional examples with more extensive integrations. Expressjs project team. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app with Express and Next.js using [Prisma](https://www.npmjs.com/package/prisma) as an ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app with Express and Next.js using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM diff --git a/src/content/docs/ko/4x/starter/generator.mdx b/src/content/docs/ko/4x/starter/generator.mdx index 859bec927e..4f22665f43 100644 --- a/src/content/docs/ko/4x/starter/generator.mdx +++ b/src/content/docs/ko/4x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force force on non-empty directory ``` -For example, the following creates an Express app named *myapp*. The app will be created in a folder named *myapp* in the current working directory and the view engine will be set to Pug: +For example, the following creates an Express app named _myapp_. The app will be created in a folder named _myapp_ in the current working directory and the view engine will be set to Pug: ```bash $ express --view=pug myapp diff --git a/src/content/docs/ko/4x/starter/hello-world.mdx b/src/content/docs/ko/4x/starter/hello-world.mdx index d92beecd0a..63821ba16e 100644 --- a/src/content/docs/ko/4x/starter/hello-world.mdx +++ b/src/content/docs/ko/4x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Embedded below is essentially the simplest Express app you can create. It is a single file app -— *not* what you'd get if you use the [Express generator](/en/starter/generator), which +— _not_ what you'd get if you use the [Express generator](/en/starter/generator), which creates the scaffolding for a full app with numerous JavaScript files, Jade templates, and sub-directories for various purposes. @@ -29,7 +29,7 @@ app.listen(port, () => { ``` This app starts a server and listens on port 3000 for connections. The app responds with "Hello World!" for requests -to the root URL (`/`) or *route*. For every other path, it will respond with a **404 Not Found**. +to the root URL (`/`) or _route_. For every other path, it will respond with a **404 Not Found**. ## Running Locally diff --git a/src/content/docs/ko/5x/guide/behind-proxies.mdx b/src/content/docs/ko/5x/guide/behind-proxies.mdx index dc509998f7..d96970dd67 100644 --- a/src/content/docs/ko/5x/guide/behind-proxies.mdx +++ b/src/content/docs/ko/5x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ When setting to `true`, it is important to ensure that the last reverse proxy tr An IP address, subnet, or an array of IP addresses and subnets to trust as being a reverse proxy. The following list shows the pre-configured subnet names: -* loopback - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` You can set IP addresses in any of the following ways: diff --git a/src/content/docs/ko/5x/guide/error-handling.mdx b/src/content/docs/ko/5x/guide/error-handling.mdx index 78f1c86e92..e34218f841 100644 --- a/src/content/docs/ko/5x/guide/error-handling.mdx +++ b/src/content/docs/ko/5x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Understand how Express.js handles errors in synchronous and asynchr import Alert from '@components/primitives/Alert/Alert.astro'; -*Error Handling* refers to how Express catches and processes errors that +_Error Handling_ refers to how Express catches and processes errors that occur both synchronously and asynchronously. Express comes with a default error handler so you don't need to write your own to get started. @@ -161,12 +161,12 @@ Set the environment variable `NODE_ENV` to `production`, to run the app in produ When an error is written, the following information is added to the response: -* The `res.statusCode` is set from `err.status` (or `err.statusCode`). If +- The `res.statusCode` is set from `err.status` (or `err.statusCode`). If this value is outside the 4xx or 5xx range, it will be set to 500. -* The `res.statusMessage` is set according to the status code. -* The body will be the HTML of the status code message when in production +- The `res.statusMessage` is set according to the status code. +- The body will be the HTML of the status code message when in production environment, otherwise will be `err.stack`. -* Any headers specified in an `err.headers` object. +- Any headers specified in an `err.headers` object. If you call `next()` with an error after you have started writing the response (for example, if you encounter an error while streaming the @@ -258,7 +258,7 @@ function logErrors(err, req, res, next) { Also in this example, `clientErrorHandler` is defined as follows; in this case, the error is explicitly passed along to the next one. -Notice that when *not* calling "next" in an error-handling function, you are responsible for writing (and ending) the response. Otherwise, those requests will "hang" and will not be eligible for garbage collection. +Notice that when _not_ calling "next" in an error-handling function, you are responsible for writing (and ending) the response. Otherwise, those requests will "hang" and will not be eligible for garbage collection. ```js function clientErrorHandler(err, req, res, next) { diff --git a/src/content/docs/ko/5x/guide/routing.mdx b/src/content/docs/ko/5x/guide/routing.mdx index 78ab64f6e8..930e7b8438 100644 --- a/src/content/docs/ko/5x/guide/routing.mdx +++ b/src/content/docs/ko/5x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Learn how to define and use routes in Express.js applications, incl import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* refers to how an application's endpoints (URIs) respond to client requests. +_Routing_ refers to how an application's endpoints (URIs) respond to client requests. For an introduction to routing, see [Basic routing](/en/starter/basic-routing). You define routing using methods of the Express `app` object that correspond to HTTP methods; @@ -52,7 +52,7 @@ app.post('/', (req, res) => { Express supports methods that correspond to all HTTP request methods: `get`, `post`, and so on. For a full list, see [app.METHOD](/en/5x/api#app.METHOD). -There is a special routing method, `app.all()`, used to load middleware functions at a path for *all* HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). +There is a special routing method, `app.all()`, used to load middleware functions at a path for _all_ HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { In this example: -* `GET /user/5` → handled by first route → sends "User 5" -* `GET /user/0` → first route calls `next('route')`, skipping to the next matching `/user/:id` route +- `GET /user/5` → handled by first route → sends "User 5" +- `GET /user/0` → first route calls `next('route')`, skipping to the next matching `/user/:id` route Route handlers can be in the form of a function, an array of functions, or combinations of both, as shown in the following examples. diff --git a/src/content/docs/ko/5x/guide/using-middleware.mdx b/src/content/docs/ko/5x/guide/using-middleware.mdx index 026542a234..36f8034ef2 100644 --- a/src/content/docs/ko/5x/guide/using-middleware.mdx +++ b/src/content/docs/ko/5x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express is a routing and middleware web framework that has minimal functionality of its own: An Express application is essentially a series of middleware function calls. -*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. +_Middleware_ functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. Middleware functions can perform the following tasks: -* Execute any code. -* Make changes to the request and the response objects. -* End the request-response cycle. -* Call the next middleware function in the stack. +- Execute any code. +- Make changes to the request and the response objects. +- End the request-response cycle. +- Call the next middleware function in the stack. If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. An Express application can use the following types of middleware: -* [Application-level middleware](#middleware.application) -* [Router-level middleware](#middleware.router) -* [Error-handling middleware](#middleware.error-handling) -* [Built-in middleware](#middleware.built-in) -* [Third-party middleware](#middleware.third-party) +- [Application-level middleware](#middleware.application) +- [Router-level middleware](#middleware.router) +- [Error-handling middleware](#middleware.error-handling) +- [Built-in middleware](#middleware.built-in) +- [Third-party middleware](#middleware.third-party) You can load application-level and router-level middleware with an optional mount path. You can also load a series of middleware functions together, which creates a sub-stack of the middleware system at a mount point. @@ -246,7 +246,7 @@ app.use('/admin', router, (req, res) => { -Error-handling middleware always takes *four* arguments. You must provide four arguments to +Error-handling middleware always takes _four_ arguments. You must provide four arguments to identify it as an error-handling middleware function. Even if you don't need to use the `next` object, you must specify it to maintain the signature. Otherwise, the `next` object will be interpreted as regular middleware and will fail to handle errors. @@ -271,9 +271,9 @@ functions that were previously included with Express are now in separate modules Express has the following built-in middleware functions: -* [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. -* [express.json](/en/5x/api#express.json) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** +- [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. +- [express.json](/en/5x/api#express.json) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** ## Third-party middleware diff --git a/src/content/docs/ko/5x/guide/using-template-engines.mdx b/src/content/docs/ko/5x/guide/using-template-engines.mdx index 7095bc6dd5..31edcdde82 100644 --- a/src/content/docs/ko/5x/guide/using-template-engines.mdx +++ b/src/content/docs/ko/5x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Discover how to integrate and use template engines like Pug, Handle import Alert from '@components/primitives/Alert/Alert.astro'; -A *template engine* enables you to use static template files in your application. At runtime, the template engine replaces +A _template engine_ enables you to use static template files in your application. At runtime, the template engine replaces variables in a template file with actual values, and transforms the template into an HTML file sent to the client. This approach makes it easier to design an HTML page. @@ -13,9 +13,9 @@ The [Express application generator](/en/starter/generator) uses [Pug](https://pu To render template files, set the following [application setting properties](/en/4x/api#app.set), in the default `app.js` created by the generator: -* `views`, the directory where the template files are located. Eg: `app.set('views', './views')`. +- `views`, the directory where the template files are located. Eg: `app.set('views', './views')`. This defaults to the `views` directory in the application root directory. -* `view engine`, the template engine to use. For example, to use the Pug template engine: `app.set('view engine', 'pug')`. +- `view engine`, the template engine to use. For example, to use the Pug template engine: `app.set('view engine', 'pug')`. Then install the corresponding template engine npm package; for example to install Pug: diff --git a/src/content/docs/ko/5x/guide/writing-middleware.mdx b/src/content/docs/ko/5x/guide/writing-middleware.mdx index a22cd12f84..507c3ac06a 100644 --- a/src/content/docs/ko/5x/guide/writing-middleware.mdx +++ b/src/content/docs/ko/5x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Learn how to write custom middleware functions for Express.js appli import Alert from '@components/primitives/Alert/Alert.astro'; -*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. +_Middleware_ functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. Middleware functions can perform the following tasks: -* Execute any code. -* Make changes to the request and the response objects. -* End the request-response cycle. -* Call the next middleware in the stack. +- Execute any code. +- Make changes to the request and the response objects. +- End the request-response cycle. +- Call the next middleware in the stack. If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. diff --git a/src/content/docs/ko/5x/starter/basic-routing.mdx b/src/content/docs/ko/5x/starter/basic-routing.mdx index 35d674808b..73c12f3893 100644 --- a/src/content/docs/ko/5x/starter/basic-routing.mdx +++ b/src/content/docs/ko/5x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Learn the fundamentals of routing in Express.js applications, inclu import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). +_Routing_ refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). Each route can have one or more handler functions, which are executed when the route is matched. @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); Where: -* `app` is an instance of `express`. -* `METHOD` is an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in lowercase. -* `PATH` is a path on the server. -* `HANDLER` is the function executed when the route is matched. +- `app` is an instance of `express`. +- `METHOD` is an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in lowercase. +- `PATH` is a path on the server. +- `HANDLER` is the function executed when the route is matched. diff --git a/src/content/docs/ko/5x/starter/examples.mdx b/src/content/docs/ko/5x/starter/examples.mdx index eccdf984c2..69f410e908 100644 --- a/src/content/docs/ko/5x/starter/examples.mdx +++ b/src/content/docs/ko/5x/starter/examples.mdx @@ -7,31 +7,31 @@ import Alert from '@components/primitives/Alert/Alert.astro'; This page contains list of examples using Express. -* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Authentication with login and password -* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - HTTP content negotiation -* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Working with cookie-based sessions -* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Working with cookies -* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transferring files to client -* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Working with Embedded JavaScript templating (ejs) -* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Creating error pages -* [error](https://github.com/expressjs/express/tree/master/examples/error) - Working with error middleware -* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Simple request handler -* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown as template engine -* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Working with multiple Express routers -* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - MVC-style controllers -* [online](https://github.com/expressjs/express/tree/master/examples/online) - Tracking online user activity with `online` and `redis` packages -* [params](https://github.com/expressjs/express/tree/master/examples/params) - Working with route parameters -* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Multiple HTTP operations on the same resource -* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organizing routes using a map -* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Working with route middleware -* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizing routes per each resource -* [search](https://github.com/expressjs/express/tree/master/examples/search) - Search API -* [session](https://github.com/expressjs/express/tree/master/examples/session) - User sessions -* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Serving static files -* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Working with virtual hosts -* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Rendering views dynamically -* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Saving data in request object between middleware calls -* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Simple API service +- [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Authentication with login and password +- [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - HTTP content negotiation +- [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Working with cookie-based sessions +- [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Working with cookies +- [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transferring files to client +- [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Working with Embedded JavaScript templating (ejs) +- [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Creating error pages +- [error](https://github.com/expressjs/express/tree/master/examples/error) - Working with error middleware +- [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Simple request handler +- [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown as template engine +- [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Working with multiple Express routers +- [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - MVC-style controllers +- [online](https://github.com/expressjs/express/tree/master/examples/online) - Tracking online user activity with `online` and `redis` packages +- [params](https://github.com/expressjs/express/tree/master/examples/params) - Working with route parameters +- [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Multiple HTTP operations on the same resource +- [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organizing routes using a map +- [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Working with route middleware +- [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizing routes per each resource +- [search](https://github.com/expressjs/express/tree/master/examples/search) - Search API +- [session](https://github.com/expressjs/express/tree/master/examples/session) - User sessions +- [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Serving static files +- [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Working with virtual hosts +- [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Rendering views dynamically +- [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Saving data in request object between middleware calls +- [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Simple API service ## Additional examples @@ -45,5 +45,5 @@ Expressjs project team. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app with Express and Next.js using [Prisma](https://www.npmjs.com/package/prisma) as an ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app with Express and Next.js using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM diff --git a/src/content/docs/ko/5x/starter/generator.mdx b/src/content/docs/ko/5x/starter/generator.mdx index 859bec927e..4f22665f43 100644 --- a/src/content/docs/ko/5x/starter/generator.mdx +++ b/src/content/docs/ko/5x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force force on non-empty directory ``` -For example, the following creates an Express app named *myapp*. The app will be created in a folder named *myapp* in the current working directory and the view engine will be set to Pug: +For example, the following creates an Express app named _myapp_. The app will be created in a folder named _myapp_ in the current working directory and the view engine will be set to Pug: ```bash $ express --view=pug myapp diff --git a/src/content/docs/ko/5x/starter/hello-world.mdx b/src/content/docs/ko/5x/starter/hello-world.mdx index d92beecd0a..63821ba16e 100644 --- a/src/content/docs/ko/5x/starter/hello-world.mdx +++ b/src/content/docs/ko/5x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Embedded below is essentially the simplest Express app you can create. It is a single file app -— *not* what you'd get if you use the [Express generator](/en/starter/generator), which +— _not_ what you'd get if you use the [Express generator](/en/starter/generator), which creates the scaffolding for a full app with numerous JavaScript files, Jade templates, and sub-directories for various purposes. @@ -29,7 +29,7 @@ app.listen(port, () => { ``` This app starts a server and listens on port 3000 for connections. The app responds with "Hello World!" for requests -to the root URL (`/`) or *route*. For every other path, it will respond with a **404 Not Found**. +to the root URL (`/`) or _route_. For every other path, it will respond with a **404 Not Found**. ## Running Locally diff --git a/src/content/docs/pt-br/4x/guide/behind-proxies.mdx b/src/content/docs/pt-br/4x/guide/behind-proxies.mdx index 1880b62ed0..e6a72e5cad 100644 --- a/src/content/docs/pt-br/4x/guide/behind-proxies.mdx +++ b/src/content/docs/pt-br/4x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ Ao definir como `true`, é importante garantir que o último proxy reverso confi Um endereço IP, subnet ou uma matriz de endereços IP e subnets para confiar como sendo um proxy reverso. A seguinte lista mostra os nomes das sub-redes pré-configuradas: -* loopback - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` Você pode definir endereços IP das seguintes maneiras: @@ -90,12 +90,13 @@ Habilitar `trust proxy` terá o seguinte impacto: `X-Forwarded-Host`, que pode ser configurado pelo cliente ou pelo proxy.
  • - `X-Forwarded-Proto` pode ser configurado pelo proxy reverso para dizer ao aplicativo se ele é `https` ou - `http` ou até mesmo um nome inválido. Este valor é refletido por [req.protocol](/en/api#req.protocol). + `X-Forwarded-Proto` pode ser configurado pelo proxy reverso para dizer ao aplicativo se ele é + `https` ou `http` ou até mesmo um nome inválido. Este valor é refletido por + [req.protocol](/en/api#req.protocol).
  • - Os valores [req.ip](/en/api#req.ip) e [req.ips](/en/api#req.ips) são preenchidos com base no cabeçalho - do socket e `X-Forwarded-For`, iniciando no primeiro endereço não confiável. + Os valores [req.ip](/en/api#req.ip) e [req.ips](/en/api#req.ips) são preenchidos com base no + cabeçalho do socket e `X-Forwarded-For`, iniciando no primeiro endereço não confiável.
    • diff --git a/src/content/docs/pt-br/4x/guide/error-handling.mdx b/src/content/docs/pt-br/4x/guide/error-handling.mdx index c0d1aa28c7..0cd431d89c 100644 --- a/src/content/docs/pt-br/4x/guide/error-handling.mdx +++ b/src/content/docs/pt-br/4x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Entenda como o Express.js lida com erros em código síncrono e ass import Alert from '@components/primitives/Alert/Alert.astro'; -*Tratamento de erros* refere-se a como as capturas Expressas e processa erros que +_Tratamento de erros_ refere-se a como as capturas Expressas e processa erros que ocorrem de forma sincronizada e assíncrona. Expresso vem com um erro padrão manipulador para que você não precise escrever seu próprio para começar. @@ -30,11 +30,11 @@ e processá-los. Por exemplo: ```js app.get('/', (req, res, next) => { - fs. eadFile('/file-does-not-existente', (err, data) => { + fs.eadFile('/file-does-not-existente', (err, data) => { if (err) { next(err); // Passa os erros para o Express. } else { - res. end(data); + res.end(data); } }); }); @@ -161,12 +161,12 @@ Defina a variável de ambiente `NODE_ENV` como `production`, para executar o apl Quando um erro é escrito, a seguinte informação é adicionada a resposta: -* O `res.statusCode` é definido em `err.status` (ou `err.statusCode`). Se +- O `res.statusCode` é definido em `err.status` (ou `err.statusCode`). Se este valor estiver fora do intervalo de 4xx ou 5xx, ele será definido como 500. -* A mensagem 'res.statusMessage' é definida de acordo com o código de status. -* O corpo será o HTML da mensagem do código de status quando em produção +- A mensagem 'res.statusMessage' é definida de acordo com o código de status. +- O corpo será o HTML da mensagem do código de status quando em produção ambiente, caso contrário será `err.stack`. -* Qualquer cabeçalho especificado em um objeto `err.headers`. +- Qualquer cabeçalho especificado em um objeto `err.headers`. Se você chamar `next()` com um erro depois que você começou a escrever a resposta (por exemplo, se você encontrar um erro ao transmitir a resposta @@ -212,12 +212,12 @@ const bodyParser = require('body-parser'); const methodOverride = require('method-override'); app.use( - bodyParser. rlencoded({ + bodyParser.rlencoded({ extendido: true, }) ); app.use(bodyParser.json()); -app. se(methodOverride()); +app.se(methodOverride()); app.use((err, req, res, next) => { // lógica }); @@ -234,12 +234,12 @@ para solicitações feitas usando `XHR` e aqueles sem: const bodyParser = require('body-parser'); const methodOverride = require('method-override'); -app. se( +app.se( bodyParser.urlencoded({ extendido: true, }) ); -app. se(bodyParser.json()); +app.se(bodyParser.json()); app.use(methodOverride()); app.use(logErrors); app.use(clientErrorHandler); @@ -258,12 +258,12 @@ function logErrors(err, req, res, ext) { Também neste exemplo, `clientErrorHandler` é definido como segue; neste caso, o erro é explicitamente passado para o próximo. -Observe que quando *não* estiver chamando "próximo" em uma função de manipulação de erros, você é responsável por escrever (e terminar) a resposta. Caso contrário, esses pedidos ficarão "pendentes" e não serão elegíveis para a recolha de lixo. +Observe que quando _não_ estiver chamando "próximo" em uma função de manipulação de erros, você é responsável por escrever (e terminar) a resposta. Caso contrário, esses pedidos ficarão "pendentes" e não serão elegíveis para a recolha de lixo. ```js function clientErrorHandler(err, req, res, next) { if (req.xhr) { - res.status(500). end({ error: 'Algo falhou!' }); + res.status(500).end({ error: 'Algo falhou!' }); } else { next(err); } diff --git a/src/content/docs/pt-br/4x/guide/routing.mdx b/src/content/docs/pt-br/4x/guide/routing.mdx index c8e9e2d7a3..52f12d9985 100644 --- a/src/content/docs/pt-br/4x/guide/routing.mdx +++ b/src/content/docs/pt-br/4x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Aprenda a definir e usar rotas em aplicações Express.js, incluind import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* refere-se a como os endpoints de um aplicativo (URIs) respondem às solicitações do cliente. +_Routing_ refere-se a como os endpoints de um aplicativo (URIs) respondem às solicitações do cliente. Para uma introdução ao roteamento, veja [Roteamento básico](/en/starter/basic-routing). Você define roteamento usando métodos do objeto Express `app` que correspondem aos métodos HTTP; @@ -26,7 +26,7 @@ const express = require('express'); const app = express(); // responda com "olá mundo" quando for feita uma solicitação GET para a página inicial -app. et('/', (req, res) => { +app.et('/', (req, res) => { res.send('hello world'); }); ``` @@ -244,10 +244,10 @@ Você pode fornecer várias funções de retorno de chamada que se comportam com ```js app.get('/user/:id', (req, res, next) => { - if (req.params. d === '0') { + if (req.params.d === '0') { return next('rota'); } - res. end(`Usuário ${req.params.id}`); + res.end(`Usuário ${req.params.id}`); }); app.get('/user/:id', (req, res) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { Neste exemplo: -* `GET /user/5` → tratado pela primeira rota → envia "Usuário 5" -* `GET /user/0` → primeira rota chama `next('rote')`, pulando para a próxima rota `/user/:id` correspondente +- `GET /user/5` → tratado pela primeira rota → envia "Usuário 5" +- `GET /user/0` → primeira rota chama `next('rote')`, pulando para a próxima rota `/user/:id` correspondente Os manipuladores de rotas podem estar na forma de uma função, um array de funções ou combinações de ambos, como mostrado nos exemplos a seguir. @@ -276,11 +276,11 @@ Mais de uma função de retorno de chamada pode manipular uma rota (certifique-s app.get( '/example/b', (req, res, next) => { - console. og('a resposta será enviada pela próxima função. .'); + console.og('a resposta será enviada pela próxima função. .'); next(); }, (req, res) => { - res. end('Olá de B!'); + res.end('Olá de B!'); } ); ``` @@ -289,17 +289,17 @@ Um array de funções de retorno de chamada pode lidar com uma rota. Por exemplo ```js const cb0 = function (req, res, next) { - console. og('CB0'); + console.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; const cb2 = function (req, res) { - res. end('Olá de C!'); + res.end('Olá de C!'); }; app.get('/example/c', [cb0, cb1, cb2]); @@ -309,24 +309,24 @@ Uma combinação de funções independentes e matrizes de funções pode lidar c ```js const cb0 = function (req, res, next) { - console. og('CB0'); + console.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; -aplicativo. et( +aplicativo.et( '/example/d', [cb0, cb1], (req, res, next) => { - console. og('a resposta será enviada pela próxima função. .'); + console.og('a resposta será enviada pela próxima função. .'); next(); }, (req, res) => { - res. end('Olá de D!'); + res.end('Olá de D!'); } ); ``` @@ -358,14 +358,14 @@ Aqui está um exemplo de manipuladores de rota encadeados que são definidos usa app .route('/book') .get((req, res) => { - res. end('Recebe um livro aleatório'); + res.end('Recebe um livro aleatório'); }) - . ost((req, res) => { + .ost((req, res) => { res.send('Adicionar um livro'); }) - . ut((req, res) => { + .ut((req, res) => { res.send('Atualizar o livro'); -}); + }); ``` ## expressão.Roteador diff --git a/src/content/docs/pt-br/4x/guide/using-middleware.mdx b/src/content/docs/pt-br/4x/guide/using-middleware.mdx index c1e4bab642..c71cab0e42 100644 --- a/src/content/docs/pt-br/4x/guide/using-middleware.mdx +++ b/src/content/docs/pt-br/4x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express é uma web framework de roteamento e middleware que tem a funcionalidade mínima de sua própria funcionalidade: Um aplicativo Express é essencialmente uma série de chamadas de função middleware. -Middleware_ são funções que têm acesso ao [objeto de requisição](/en/5x/api#req) (`req`), a [objeto de resposta](/en/5x/api#res) (`res`) e a próxima função de middleware no ciclo de resposta de solicitação do aplicativo. A próxima função de middleware é comumente denotada por uma variável chamada `next`. +Middleware\_ são funções que têm acesso ao [objeto de requisição](/en/5x/api#req) (`req`), a [objeto de resposta](/en/5x/api#res) (`res`) e a próxima função de middleware no ciclo de resposta de solicitação do aplicativo. A próxima função de middleware é comumente denotada por uma variável chamada `next`. As funções do Middleware podem executar as seguintes tarefas: -* Execute qualquer código. -* Fazer alterações na solicitação e nos objetos de resposta. -* Encerrar o ciclo de solicitação-resposta. -* Chame a próxima função middleware na pilha. +- Execute qualquer código. +- Fazer alterações na solicitação e nos objetos de resposta. +- Encerrar o ciclo de solicitação-resposta. +- Chame a próxima função middleware na pilha. Se a função middleware atual não encerra o ciclo de resposta de solicitação, ela deve chamar `next()` para passar o controle para a próxima função middleware. Caso contrário, o pedido ficará pendurado. Um aplicativo Express pode usar os seguintes tipos de middleware: -* [Meio do aplicativo](#middleware.application) -* [Meio do roteador](#middleware.router) -* [Middleware com erro](#middleware.error-handling) -* [middleware](#middleware.built-in) -* [Middleware de terceiros](#middleware.third-party) +- [Meio do aplicativo](#middleware.application) +- [Meio do roteador](#middleware.router) +- [Middleware com erro](#middleware.error-handling) +- [middleware](#middleware.built-in) +- [Middleware de terceiros](#middleware.third-party) Você pode carregar o nível de aplicação e middleware de nível de roteador com um caminho de montagem opcional. Você também pode carregar uma série de funções intermediárias juntas, o que cria uma sub-pilha do sistema intermediário em um ponto de montagem. @@ -88,16 +88,16 @@ Este exemplo mostra uma sub-pilha de middleware que lida com requisições GET p app.get( '/user/:id', (req, res, next) => { - console.log('ID:', req. arams.id); + console.log('ID:', req.arams.id); next(); }, (req, res, next) => { - res. end('Informações do usuário'); + res.end('Informações do usuário'); } ); // manipulador para o caminho /user/:id, que imprime o ID do usuário -aplicativo. et('/user/:id', (req, res, next) => { +aplicativo.et('/user/:id', (req, res, next) => { res.send(req.params.id); }); ``` @@ -140,17 +140,17 @@ Este exemplo mostra um array com um sub-stack de middleware que lida com requisi ```js function logOriginalUrl(req, res, próximo) { - console.log('Solicitação URL:', req. riginalUrl); + console.log('Solicitação URL:', req.riginalUrl); next(); } function logMethod(req, res, ext) { - console.log('Request Type:', req. ethod); + console.log('Request Type:', req.ethod); next(); } const logStuff = [logOriginalUrl, logMethod]; -app. et('/user/:id', logStuff, (req, res, next) => { +app.et('/user/:id', logStuff, (req, res, next) => { res.send('Usuário Info'); }); ``` @@ -246,7 +246,7 @@ router. et('/user/:id', (req, res) => { -O middleware com erros de manipulação sempre toma *quatro* argumentos. Você deve fornecer quatro argumentos para +O middleware com erros de manipulação sempre toma _quatro_ argumentos. Você deve fornecer quatro argumentos para identificá-lo como uma função de middleware manipulação de erros. Mesmo se você não precisar usar o objeto `next` , você deve especificá-lo para manter a assinatura. Caso contrário, o objeto `próximo` será interpretado como um middleware regular e irá falhar em lidar com erros. @@ -271,9 +271,9 @@ funções que foram previamente incluídas com Express estão agora em módulos O Express tem as seguintes funções de middleware incorporadas: -* [express.static](/en/5x/api#express.static) serve como arquivos estáticos, como arquivos HTML, imagens e assim por diante. -* [express.json](/en/5x/api#express.json) analisa solicitações recebidas com carga JSON. **NOTA: Disponível com Expresso 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) analisa solicitações recebidas com payloads codificados por URL. **NOTA: Disponível com Expresso 4.16.0+** +- [express.static](/en/5x/api#express.static) serve como arquivos estáticos, como arquivos HTML, imagens e assim por diante. +- [express.json](/en/5x/api#express.json) analisa solicitações recebidas com carga JSON. **NOTA: Disponível com Expresso 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) analisa solicitações recebidas com payloads codificados por URL. **NOTA: Disponível com Expresso 4.16.0+** ## Midddleware de terceiros diff --git a/src/content/docs/pt-br/4x/guide/using-template-engines.mdx b/src/content/docs/pt-br/4x/guide/using-template-engines.mdx index ff8b9c8e16..a213cb8b94 100644 --- a/src/content/docs/pt-br/4x/guide/using-template-engines.mdx +++ b/src/content/docs/pt-br/4x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Descubra como integrar e usar mecanismos de modelos como Pug, Handl import Alert from '@components/primitives/Alert/Alert.astro'; -Um *motor de template* permite que você use arquivos de template estáticos na sua aplicação. At runtime, the template engine replaces +Um _motor de template_ permite que você use arquivos de template estáticos na sua aplicação. At runtime, the template engine replaces variables in a template file with actual values, and transforms the template into an HTML file sent to the client. Esta abordagem torna mais fácil projetar uma página HTML. @@ -13,9 +13,9 @@ O [gerador de aplicação Expressa](/en/starter/generator) usa [Pug](https://pug Para renderizar arquivos de template, defina as seguintes [propriedades de configuração da aplicação](/en/4x/api#app.set), no `app.js` padrão criado pelo gerador: -* `views`, o diretório onde se localizam os arquivos de template. Ex: `app.set('views', './views')`. +- `views`, o diretório onde se localizam os arquivos de template. Ex: `app.set('views', './views')`. Isto é padrão para o diretório `views` no diretório raiz do aplicativo. -* `ver engenho`, o mecanismo de modelos a ser usado. Por exemplo, para usar o motor de template Pug: `app.set('engenharia de visualização', 'pug')`. +- `ver engenho`, o mecanismo de modelos a ser usado. Por exemplo, para usar o motor de template Pug: `app.set('engenharia de visualização', 'pug')`. Então instale o correspondente mecanismo de template do npm pacote; por exemplo, para instalar o Pug: diff --git a/src/content/docs/pt-br/4x/guide/writing-middleware.mdx b/src/content/docs/pt-br/4x/guide/writing-middleware.mdx index 3fb77ab014..6b78dbab89 100644 --- a/src/content/docs/pt-br/4x/guide/writing-middleware.mdx +++ b/src/content/docs/pt-br/4x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Aprenda a escrever funções de middleware personalizadas para apli import Alert from '@components/primitives/Alert/Alert.astro'; -Middleware_ são funções que têm acesso ao [objeto de requisição](/en/5x/api#req) (`req`), a [objeto de resposta](/en/5x/api#res) (`res`) e a função `next` no ciclo de resposta de solicitação do aplicativo. A função `próxima` é uma função no roteador Expresso que, quando invocado, executa o intermediário sucedendo ao intermediário atual. +Middleware\_ são funções que têm acesso ao [objeto de requisição](/en/5x/api#req) (`req`), a [objeto de resposta](/en/5x/api#res) (`res`) e a função `next` no ciclo de resposta de solicitação do aplicativo. A função `próxima` é uma função no roteador Expresso que, quando invocado, executa o intermediário sucedendo ao intermediário atual. As funções do Middleware podem executar as seguintes tarefas: -* Execute qualquer código. -* Fazer alterações na solicitação e nos objetos de resposta. -* Encerrar o ciclo de solicitação-resposta. -* Chame o próximo middleware na pilha. +- Execute qualquer código. +- Fazer alterações na solicitação e nos objetos de resposta. +- Encerrar o ciclo de solicitação-resposta. +- Chame o próximo middleware na pilha. Se a função middleware atual não encerra o ciclo de resposta de solicitação, ela deve chamar `next()` para passar o controle para a próxima função middleware. Caso contrário, o pedido ficará pendurado. @@ -40,8 +40,8 @@ A figura a seguir mostra os elementos de uma chamada de função middleware:
    - HTTP resposta argumento para a função middleware, chamada de "res" pela convenção - . + HTTP resposta argumento para a função middleware, chamada de "res" + pela convenção .
    HTTP request argumento para a função middleware, chamado de "req" pela convenção.
    @@ -100,7 +100,7 @@ const express = require('express'); const app = express(); const myLogger = function (req, res, next) { - console. og('LOGGED'); + console.og('LOGGED'); next(); }; @@ -140,16 +140,16 @@ const express = require('express'); const app = express(); const requestTime = function (req, res, next) { - req. equestTime = Date.now(); + req.equestTime = Date.now(); next(); }; app.use(requestTime); -aplicativo. et('/', (req, res) => { +aplicativo.et('/', (req, res) => { let responseText = 'Olá Mundo!
    '; responseText += `Solicitado em: ${req.requestTime}`; - res. end(responseText); + res.end(responseText); }); app.listen(3000); diff --git a/src/content/docs/pt-br/4x/starter/basic-routing.mdx b/src/content/docs/pt-br/4x/starter/basic-routing.mdx index ea9db985e3..6dced5a72b 100644 --- a/src/content/docs/pt-br/4x/starter/basic-routing.mdx +++ b/src/content/docs/pt-br/4x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Aprenda os fundamentos do roteamento em aplicações Express.js, in import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* refere-se a determinar como uma aplicação responde a uma solicitação do cliente para um ponto final específico, que é um URI (ou caminho) e um método de requisição HTTP específico (GET, POST, e assim por diante). +_Routing_ refere-se a determinar como uma aplicação responde a uma solicitação do cliente para um ponto final específico, que é um URI (ou caminho) e um método de requisição HTTP específico (GET, POST, e assim por diante). Cada rota pode ter uma ou mais funções de manipulador, que são executadas quando a rota é correspondente. @@ -17,10 +17,10 @@ app.METHOD(PATH, MUITO); Onde: -* `app` é uma instância de `express`. -* `METHOD` é um [método de solicitação HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), em minúsculas. -* O `PATH` é um caminho no servidor. -* `HANDLER` é a função executada quando a rota é correspondente. +- `app` é uma instância de `express`. +- `METHOD` é um [método de solicitação HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), em minúsculas. +- O `PATH` é um caminho no servidor. +- `HANDLER` é a função executada quando a rota é correspondente. diff --git a/src/content/docs/pt-br/4x/starter/examples.mdx b/src/content/docs/pt-br/4x/starter/examples.mdx index a4dfced43d..ff0c62c56f 100644 --- a/src/content/docs/pt-br/4x/starter/examples.mdx +++ b/src/content/docs/pt-br/4x/starter/examples.mdx @@ -5,41 +5,41 @@ description: Explore uma coleção de exemplos de aplicativos do Express.js cobr import Alert from '@components/primitives/Alert/Alert.astro'; -* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Autenticação com login e senha -* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - negociação de conteúdo HTTP -* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Trabalhando com sessões baseadas em cookies -* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Trabalhando com cookies -* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transferindo arquivos para o cliente -* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Trabalhando com template JavaScript embutido (ejs) -* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Criando páginas de erro -* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Trabalhando com um middleware de erro -* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Manipulador de requisições simples -* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown como mecanismo de modelo -* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Trabalhando com vários roteadores Expressos -* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - controladores do estilo MVC -* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Rastreando atividade de usuário online com pacotes `online` e `redis` -* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Trabalhando com parâmetros de rotas -* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Várias operações HTTP no mesmo recurso -* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organização de rotas usando um mapa -* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Trabalhando com sistema de middleware -* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizando rotas por recurso -* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Pesquisa API -* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - Sessões de usuário -* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Servendo arquivos estáticos -* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Trabalhando com hosts virtuais -* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Renderizando visualizações dinamicamente -* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Salvando dados no objeto da solicitação entre chamadas de middleware -* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Serviço de API simples +- [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Autenticação com login e senha +- [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - negociação de conteúdo HTTP +- [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Trabalhando com sessões baseadas em cookies +- [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Trabalhando com cookies +- [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transferindo arquivos para o cliente +- [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Trabalhando com template JavaScript embutido (ejs) +- [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Criando páginas de erro +- [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Trabalhando com um middleware de erro +- [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Manipulador de requisições simples +- [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown como mecanismo de modelo +- [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Trabalhando com vários roteadores Expressos +- [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - controladores do estilo MVC +- [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Rastreando atividade de usuário online com pacotes `online` e `redis` +- [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Trabalhando com parâmetros de rotas +- [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Várias operações HTTP no mesmo recurso +- [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organização de rotas usando um mapa +- [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Trabalhando com sistema de middleware +- [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizando rotas por recurso +- [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Pesquisa API +- [session](https://github.com/expressjs/express/tree/4.x/examples/session) - Sessões de usuário +- [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Servendo arquivos estáticos +- [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Trabalhando com hosts virtuais +- [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Renderizando visualizações dinamicamente +- [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Salvando dados no objeto da solicitação entre chamadas de middleware +- [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Serviço de API simples ## Exemplos adicionais Estes são alguns exemplos adicionais com integrações mais extensas. - Esta informação refere-se a sites de terceiros, produtos ou módulos que não são mantidos pela equipe - Expressjs. Listar aqui não constitui um endosso ou recomendação da equipe de projeto + Esta informação refere-se a sites de terceiros, produtos ou módulos que não são mantidos pela + equipe Expressjs. Listar aqui não constitui um endosso ou recomendação da equipe de projeto Expressjs. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Aplicativo Fullstack com Express and Next.js usando [Prisma](https://www.npmjs.com/package/prisma) como ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - API REST com Express in TypeScript usando [Prisma](https://www.npmjs.com/package/prisma) como ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Aplicativo Fullstack com Express and Next.js usando [Prisma](https://www.npmjs.com/package/prisma) como ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - API REST com Express in TypeScript usando [Prisma](https://www.npmjs.com/package/prisma) como ORM diff --git a/src/content/docs/pt-br/4x/starter/generator.mdx b/src/content/docs/pt-br/4x/starter/generator.mdx index d2c4fade8e..44d8308549 100644 --- a/src/content/docs/pt-br/4x/starter/generator.mdx +++ b/src/content/docs/pt-br/4x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force força em diretório não-vazio ``` -Por exemplo, o seguinte cria um aplicativo Expresso chamado *myapp*. O aplicativo será criado em uma pasta chamada *myapp* no diretório de trabalho atual e o mecanismo de visualização será definido para Pug: +Por exemplo, o seguinte cria um aplicativo Expresso chamado _myapp_. O aplicativo será criado em uma pasta chamada _myapp_ no diretório de trabalho atual e o mecanismo de visualização será definido para Pug: ```bash $ express --view=pug meuapp @@ -105,11 +105,11 @@ package. son ── imagens ├── javascripts ├── stylesheets -── style styesheets +── style styesheets ─ style. ss ── rotas ├── index.js -─── usuarios +─── usuarios . s ── visões erros de ── . ug diff --git a/src/content/docs/pt-br/4x/starter/hello-world.mdx b/src/content/docs/pt-br/4x/starter/hello-world.mdx index 0680e55315..3410dc5564 100644 --- a/src/content/docs/pt-br/4x/starter/hello-world.mdx +++ b/src/content/docs/pt-br/4x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Embutido abaixo é essencialmente o aplicativo Expresso mais simples que você pode criar. É um único aplicativo de arquivo -— *não* o que você obteria se usar o [Express generator](/en/starter/generator), que +— _não_ o que você obteria se usar o [Express generator](/en/starter/generator), que cria o andaime para um aplicativo completo com vários arquivos JavaScript, modelos Jade e subdiretórios para vários fins. @@ -20,7 +20,7 @@ const app = express(); const port = 3000; app.get('/', (req, res) => { - res. end('Olá Mundo!'); + res.end('Olá Mundo!'); }); app.listen(port, () => { @@ -29,7 +29,7 @@ app.listen(port, () => { ``` Este aplicativo inicia um servidor e escuta na porta 3000 para conexões. O aplicativo responde com "Olá Mundo!" para solicitações -para a URL raiz (`/`) ou *route*. Para todos os outros caminhos, responderá com um **404 Não Encontrado**. +para a URL raiz (`/`) ou _route_. Para todos os outros caminhos, responderá com um **404 Não Encontrado**. ## Executando localmente diff --git a/src/content/docs/pt-br/5x/guide/behind-proxies.mdx b/src/content/docs/pt-br/5x/guide/behind-proxies.mdx index 1880b62ed0..e6a72e5cad 100644 --- a/src/content/docs/pt-br/5x/guide/behind-proxies.mdx +++ b/src/content/docs/pt-br/5x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ Ao definir como `true`, é importante garantir que o último proxy reverso confi Um endereço IP, subnet ou uma matriz de endereços IP e subnets para confiar como sendo um proxy reverso. A seguinte lista mostra os nomes das sub-redes pré-configuradas: -* loopback - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` Você pode definir endereços IP das seguintes maneiras: @@ -90,12 +90,13 @@ Habilitar `trust proxy` terá o seguinte impacto: `X-Forwarded-Host`, que pode ser configurado pelo cliente ou pelo proxy.
  • - `X-Forwarded-Proto` pode ser configurado pelo proxy reverso para dizer ao aplicativo se ele é `https` ou - `http` ou até mesmo um nome inválido. Este valor é refletido por [req.protocol](/en/api#req.protocol). + `X-Forwarded-Proto` pode ser configurado pelo proxy reverso para dizer ao aplicativo se ele é + `https` ou `http` ou até mesmo um nome inválido. Este valor é refletido por + [req.protocol](/en/api#req.protocol).
  • - Os valores [req.ip](/en/api#req.ip) e [req.ips](/en/api#req.ips) são preenchidos com base no cabeçalho - do socket e `X-Forwarded-For`, iniciando no primeiro endereço não confiável. + Os valores [req.ip](/en/api#req.ip) e [req.ips](/en/api#req.ips) são preenchidos com base no + cabeçalho do socket e `X-Forwarded-For`, iniciando no primeiro endereço não confiável.
    • diff --git a/src/content/docs/pt-br/5x/guide/error-handling.mdx b/src/content/docs/pt-br/5x/guide/error-handling.mdx index c0d1aa28c7..0cd431d89c 100644 --- a/src/content/docs/pt-br/5x/guide/error-handling.mdx +++ b/src/content/docs/pt-br/5x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Entenda como o Express.js lida com erros em código síncrono e ass import Alert from '@components/primitives/Alert/Alert.astro'; -*Tratamento de erros* refere-se a como as capturas Expressas e processa erros que +_Tratamento de erros_ refere-se a como as capturas Expressas e processa erros que ocorrem de forma sincronizada e assíncrona. Expresso vem com um erro padrão manipulador para que você não precise escrever seu próprio para começar. @@ -30,11 +30,11 @@ e processá-los. Por exemplo: ```js app.get('/', (req, res, next) => { - fs. eadFile('/file-does-not-existente', (err, data) => { + fs.eadFile('/file-does-not-existente', (err, data) => { if (err) { next(err); // Passa os erros para o Express. } else { - res. end(data); + res.end(data); } }); }); @@ -161,12 +161,12 @@ Defina a variável de ambiente `NODE_ENV` como `production`, para executar o apl Quando um erro é escrito, a seguinte informação é adicionada a resposta: -* O `res.statusCode` é definido em `err.status` (ou `err.statusCode`). Se +- O `res.statusCode` é definido em `err.status` (ou `err.statusCode`). Se este valor estiver fora do intervalo de 4xx ou 5xx, ele será definido como 500. -* A mensagem 'res.statusMessage' é definida de acordo com o código de status. -* O corpo será o HTML da mensagem do código de status quando em produção +- A mensagem 'res.statusMessage' é definida de acordo com o código de status. +- O corpo será o HTML da mensagem do código de status quando em produção ambiente, caso contrário será `err.stack`. -* Qualquer cabeçalho especificado em um objeto `err.headers`. +- Qualquer cabeçalho especificado em um objeto `err.headers`. Se você chamar `next()` com um erro depois que você começou a escrever a resposta (por exemplo, se você encontrar um erro ao transmitir a resposta @@ -212,12 +212,12 @@ const bodyParser = require('body-parser'); const methodOverride = require('method-override'); app.use( - bodyParser. rlencoded({ + bodyParser.rlencoded({ extendido: true, }) ); app.use(bodyParser.json()); -app. se(methodOverride()); +app.se(methodOverride()); app.use((err, req, res, next) => { // lógica }); @@ -234,12 +234,12 @@ para solicitações feitas usando `XHR` e aqueles sem: const bodyParser = require('body-parser'); const methodOverride = require('method-override'); -app. se( +app.se( bodyParser.urlencoded({ extendido: true, }) ); -app. se(bodyParser.json()); +app.se(bodyParser.json()); app.use(methodOverride()); app.use(logErrors); app.use(clientErrorHandler); @@ -258,12 +258,12 @@ function logErrors(err, req, res, ext) { Também neste exemplo, `clientErrorHandler` é definido como segue; neste caso, o erro é explicitamente passado para o próximo. -Observe que quando *não* estiver chamando "próximo" em uma função de manipulação de erros, você é responsável por escrever (e terminar) a resposta. Caso contrário, esses pedidos ficarão "pendentes" e não serão elegíveis para a recolha de lixo. +Observe que quando _não_ estiver chamando "próximo" em uma função de manipulação de erros, você é responsável por escrever (e terminar) a resposta. Caso contrário, esses pedidos ficarão "pendentes" e não serão elegíveis para a recolha de lixo. ```js function clientErrorHandler(err, req, res, next) { if (req.xhr) { - res.status(500). end({ error: 'Algo falhou!' }); + res.status(500).end({ error: 'Algo falhou!' }); } else { next(err); } diff --git a/src/content/docs/pt-br/5x/guide/routing.mdx b/src/content/docs/pt-br/5x/guide/routing.mdx index c8e9e2d7a3..52f12d9985 100644 --- a/src/content/docs/pt-br/5x/guide/routing.mdx +++ b/src/content/docs/pt-br/5x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Aprenda a definir e usar rotas em aplicações Express.js, incluind import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* refere-se a como os endpoints de um aplicativo (URIs) respondem às solicitações do cliente. +_Routing_ refere-se a como os endpoints de um aplicativo (URIs) respondem às solicitações do cliente. Para uma introdução ao roteamento, veja [Roteamento básico](/en/starter/basic-routing). Você define roteamento usando métodos do objeto Express `app` que correspondem aos métodos HTTP; @@ -26,7 +26,7 @@ const express = require('express'); const app = express(); // responda com "olá mundo" quando for feita uma solicitação GET para a página inicial -app. et('/', (req, res) => { +app.et('/', (req, res) => { res.send('hello world'); }); ``` @@ -244,10 +244,10 @@ Você pode fornecer várias funções de retorno de chamada que se comportam com ```js app.get('/user/:id', (req, res, next) => { - if (req.params. d === '0') { + if (req.params.d === '0') { return next('rota'); } - res. end(`Usuário ${req.params.id}`); + res.end(`Usuário ${req.params.id}`); }); app.get('/user/:id', (req, res) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { Neste exemplo: -* `GET /user/5` → tratado pela primeira rota → envia "Usuário 5" -* `GET /user/0` → primeira rota chama `next('rote')`, pulando para a próxima rota `/user/:id` correspondente +- `GET /user/5` → tratado pela primeira rota → envia "Usuário 5" +- `GET /user/0` → primeira rota chama `next('rote')`, pulando para a próxima rota `/user/:id` correspondente Os manipuladores de rotas podem estar na forma de uma função, um array de funções ou combinações de ambos, como mostrado nos exemplos a seguir. @@ -276,11 +276,11 @@ Mais de uma função de retorno de chamada pode manipular uma rota (certifique-s app.get( '/example/b', (req, res, next) => { - console. og('a resposta será enviada pela próxima função. .'); + console.og('a resposta será enviada pela próxima função. .'); next(); }, (req, res) => { - res. end('Olá de B!'); + res.end('Olá de B!'); } ); ``` @@ -289,17 +289,17 @@ Um array de funções de retorno de chamada pode lidar com uma rota. Por exemplo ```js const cb0 = function (req, res, next) { - console. og('CB0'); + console.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; const cb2 = function (req, res) { - res. end('Olá de C!'); + res.end('Olá de C!'); }; app.get('/example/c', [cb0, cb1, cb2]); @@ -309,24 +309,24 @@ Uma combinação de funções independentes e matrizes de funções pode lidar c ```js const cb0 = function (req, res, next) { - console. og('CB0'); + console.og('CB0'); next(); }; const cb1 = function (req, res, next) { - console. og('CB1'); + console.og('CB1'); next(); }; -aplicativo. et( +aplicativo.et( '/example/d', [cb0, cb1], (req, res, next) => { - console. og('a resposta será enviada pela próxima função. .'); + console.og('a resposta será enviada pela próxima função. .'); next(); }, (req, res) => { - res. end('Olá de D!'); + res.end('Olá de D!'); } ); ``` @@ -358,14 +358,14 @@ Aqui está um exemplo de manipuladores de rota encadeados que são definidos usa app .route('/book') .get((req, res) => { - res. end('Recebe um livro aleatório'); + res.end('Recebe um livro aleatório'); }) - . ost((req, res) => { + .ost((req, res) => { res.send('Adicionar um livro'); }) - . ut((req, res) => { + .ut((req, res) => { res.send('Atualizar o livro'); -}); + }); ``` ## expressão.Roteador diff --git a/src/content/docs/pt-br/5x/guide/using-middleware.mdx b/src/content/docs/pt-br/5x/guide/using-middleware.mdx index c1e4bab642..c71cab0e42 100644 --- a/src/content/docs/pt-br/5x/guide/using-middleware.mdx +++ b/src/content/docs/pt-br/5x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express é uma web framework de roteamento e middleware que tem a funcionalidade mínima de sua própria funcionalidade: Um aplicativo Express é essencialmente uma série de chamadas de função middleware. -Middleware_ são funções que têm acesso ao [objeto de requisição](/en/5x/api#req) (`req`), a [objeto de resposta](/en/5x/api#res) (`res`) e a próxima função de middleware no ciclo de resposta de solicitação do aplicativo. A próxima função de middleware é comumente denotada por uma variável chamada `next`. +Middleware\_ são funções que têm acesso ao [objeto de requisição](/en/5x/api#req) (`req`), a [objeto de resposta](/en/5x/api#res) (`res`) e a próxima função de middleware no ciclo de resposta de solicitação do aplicativo. A próxima função de middleware é comumente denotada por uma variável chamada `next`. As funções do Middleware podem executar as seguintes tarefas: -* Execute qualquer código. -* Fazer alterações na solicitação e nos objetos de resposta. -* Encerrar o ciclo de solicitação-resposta. -* Chame a próxima função middleware na pilha. +- Execute qualquer código. +- Fazer alterações na solicitação e nos objetos de resposta. +- Encerrar o ciclo de solicitação-resposta. +- Chame a próxima função middleware na pilha. Se a função middleware atual não encerra o ciclo de resposta de solicitação, ela deve chamar `next()` para passar o controle para a próxima função middleware. Caso contrário, o pedido ficará pendurado. Um aplicativo Express pode usar os seguintes tipos de middleware: -* [Meio do aplicativo](#middleware.application) -* [Meio do roteador](#middleware.router) -* [Middleware com erro](#middleware.error-handling) -* [middleware](#middleware.built-in) -* [Middleware de terceiros](#middleware.third-party) +- [Meio do aplicativo](#middleware.application) +- [Meio do roteador](#middleware.router) +- [Middleware com erro](#middleware.error-handling) +- [middleware](#middleware.built-in) +- [Middleware de terceiros](#middleware.third-party) Você pode carregar o nível de aplicação e middleware de nível de roteador com um caminho de montagem opcional. Você também pode carregar uma série de funções intermediárias juntas, o que cria uma sub-pilha do sistema intermediário em um ponto de montagem. @@ -88,16 +88,16 @@ Este exemplo mostra uma sub-pilha de middleware que lida com requisições GET p app.get( '/user/:id', (req, res, next) => { - console.log('ID:', req. arams.id); + console.log('ID:', req.arams.id); next(); }, (req, res, next) => { - res. end('Informações do usuário'); + res.end('Informações do usuário'); } ); // manipulador para o caminho /user/:id, que imprime o ID do usuário -aplicativo. et('/user/:id', (req, res, next) => { +aplicativo.et('/user/:id', (req, res, next) => { res.send(req.params.id); }); ``` @@ -140,17 +140,17 @@ Este exemplo mostra um array com um sub-stack de middleware que lida com requisi ```js function logOriginalUrl(req, res, próximo) { - console.log('Solicitação URL:', req. riginalUrl); + console.log('Solicitação URL:', req.riginalUrl); next(); } function logMethod(req, res, ext) { - console.log('Request Type:', req. ethod); + console.log('Request Type:', req.ethod); next(); } const logStuff = [logOriginalUrl, logMethod]; -app. et('/user/:id', logStuff, (req, res, next) => { +app.et('/user/:id', logStuff, (req, res, next) => { res.send('Usuário Info'); }); ``` @@ -246,7 +246,7 @@ router. et('/user/:id', (req, res) => { -O middleware com erros de manipulação sempre toma *quatro* argumentos. Você deve fornecer quatro argumentos para +O middleware com erros de manipulação sempre toma _quatro_ argumentos. Você deve fornecer quatro argumentos para identificá-lo como uma função de middleware manipulação de erros. Mesmo se você não precisar usar o objeto `next` , você deve especificá-lo para manter a assinatura. Caso contrário, o objeto `próximo` será interpretado como um middleware regular e irá falhar em lidar com erros. @@ -271,9 +271,9 @@ funções que foram previamente incluídas com Express estão agora em módulos O Express tem as seguintes funções de middleware incorporadas: -* [express.static](/en/5x/api#express.static) serve como arquivos estáticos, como arquivos HTML, imagens e assim por diante. -* [express.json](/en/5x/api#express.json) analisa solicitações recebidas com carga JSON. **NOTA: Disponível com Expresso 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) analisa solicitações recebidas com payloads codificados por URL. **NOTA: Disponível com Expresso 4.16.0+** +- [express.static](/en/5x/api#express.static) serve como arquivos estáticos, como arquivos HTML, imagens e assim por diante. +- [express.json](/en/5x/api#express.json) analisa solicitações recebidas com carga JSON. **NOTA: Disponível com Expresso 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) analisa solicitações recebidas com payloads codificados por URL. **NOTA: Disponível com Expresso 4.16.0+** ## Midddleware de terceiros diff --git a/src/content/docs/pt-br/5x/guide/using-template-engines.mdx b/src/content/docs/pt-br/5x/guide/using-template-engines.mdx index ff8b9c8e16..a213cb8b94 100644 --- a/src/content/docs/pt-br/5x/guide/using-template-engines.mdx +++ b/src/content/docs/pt-br/5x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Descubra como integrar e usar mecanismos de modelos como Pug, Handl import Alert from '@components/primitives/Alert/Alert.astro'; -Um *motor de template* permite que você use arquivos de template estáticos na sua aplicação. At runtime, the template engine replaces +Um _motor de template_ permite que você use arquivos de template estáticos na sua aplicação. At runtime, the template engine replaces variables in a template file with actual values, and transforms the template into an HTML file sent to the client. Esta abordagem torna mais fácil projetar uma página HTML. @@ -13,9 +13,9 @@ O [gerador de aplicação Expressa](/en/starter/generator) usa [Pug](https://pug Para renderizar arquivos de template, defina as seguintes [propriedades de configuração da aplicação](/en/4x/api#app.set), no `app.js` padrão criado pelo gerador: -* `views`, o diretório onde se localizam os arquivos de template. Ex: `app.set('views', './views')`. +- `views`, o diretório onde se localizam os arquivos de template. Ex: `app.set('views', './views')`. Isto é padrão para o diretório `views` no diretório raiz do aplicativo. -* `ver engenho`, o mecanismo de modelos a ser usado. Por exemplo, para usar o motor de template Pug: `app.set('engenharia de visualização', 'pug')`. +- `ver engenho`, o mecanismo de modelos a ser usado. Por exemplo, para usar o motor de template Pug: `app.set('engenharia de visualização', 'pug')`. Então instale o correspondente mecanismo de template do npm pacote; por exemplo, para instalar o Pug: diff --git a/src/content/docs/pt-br/5x/guide/writing-middleware.mdx b/src/content/docs/pt-br/5x/guide/writing-middleware.mdx index 1eefc7c736..52afbbf6ba 100644 --- a/src/content/docs/pt-br/5x/guide/writing-middleware.mdx +++ b/src/content/docs/pt-br/5x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Aprenda a escrever funções de middleware personalizadas para apli import Alert from '@components/primitives/Alert/Alert.astro'; -Middleware_ são funções que têm acesso ao [objeto de requisição](/en/5x/api#req) (`req`), a [objeto de resposta](/en/5x/api#res) (`res`) e a função `next` no ciclo de resposta de solicitação do aplicativo. A função `próxima` é uma função no roteador Expresso que, quando invocado, executa o intermediário sucedendo ao intermediário atual. +Middleware\_ são funções que têm acesso ao [objeto de requisição](/en/5x/api#req) (`req`), a [objeto de resposta](/en/5x/api#res) (`res`) e a função `next` no ciclo de resposta de solicitação do aplicativo. A função `próxima` é uma função no roteador Expresso que, quando invocado, executa o intermediário sucedendo ao intermediário atual. As funções do Middleware podem executar as seguintes tarefas: -* Execute qualquer código. -* Fazer alterações na solicitação e nos objetos de resposta. -* Encerrar o ciclo de solicitação-resposta. -* Chame o próximo middleware na pilha. +- Execute qualquer código. +- Fazer alterações na solicitação e nos objetos de resposta. +- Encerrar o ciclo de solicitação-resposta. +- Chame o próximo middleware na pilha. Se a função middleware atual não encerra o ciclo de resposta de solicitação, ela deve chamar `next()` para passar o controle para a próxima função middleware. Caso contrário, o pedido ficará pendurado. @@ -70,7 +70,7 @@ const express = require('express'); const app = express(); const myLogger = function (req, res, next) { - console. og('LOGGED'); + console.og('LOGGED'); next(); }; @@ -110,16 +110,16 @@ const express = require('express'); const app = express(); const requestTime = function (req, res, next) { - req. equestTime = Date.now(); + req.equestTime = Date.now(); next(); }; app.use(requestTime); -aplicativo. et('/', (req, res) => { +aplicativo.et('/', (req, res) => { let responseText = 'Olá Mundo!
    '; responseText += `Solicitado em: ${req.requestTime}`; - res. end(responseText); + res.end(responseText); }); app.listen(3000); diff --git a/src/content/docs/pt-br/5x/starter/basic-routing.mdx b/src/content/docs/pt-br/5x/starter/basic-routing.mdx index ea9db985e3..6dced5a72b 100644 --- a/src/content/docs/pt-br/5x/starter/basic-routing.mdx +++ b/src/content/docs/pt-br/5x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Aprenda os fundamentos do roteamento em aplicações Express.js, in import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* refere-se a determinar como uma aplicação responde a uma solicitação do cliente para um ponto final específico, que é um URI (ou caminho) e um método de requisição HTTP específico (GET, POST, e assim por diante). +_Routing_ refere-se a determinar como uma aplicação responde a uma solicitação do cliente para um ponto final específico, que é um URI (ou caminho) e um método de requisição HTTP específico (GET, POST, e assim por diante). Cada rota pode ter uma ou mais funções de manipulador, que são executadas quando a rota é correspondente. @@ -17,10 +17,10 @@ app.METHOD(PATH, MUITO); Onde: -* `app` é uma instância de `express`. -* `METHOD` é um [método de solicitação HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), em minúsculas. -* O `PATH` é um caminho no servidor. -* `HANDLER` é a função executada quando a rota é correspondente. +- `app` é uma instância de `express`. +- `METHOD` é um [método de solicitação HTTP](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), em minúsculas. +- O `PATH` é um caminho no servidor. +- `HANDLER` é a função executada quando a rota é correspondente. diff --git a/src/content/docs/pt-br/5x/starter/examples.mdx b/src/content/docs/pt-br/5x/starter/examples.mdx index 7f0f80668c..d7c62b03ab 100644 --- a/src/content/docs/pt-br/5x/starter/examples.mdx +++ b/src/content/docs/pt-br/5x/starter/examples.mdx @@ -7,31 +7,31 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Esta página contém a lista de exemplos usando o Express. -* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Autenticação com login e senha -* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - negociação de conteúdo HTTP -* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Trabalhando com sessões baseadas em cookies -* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Trabalhando com cookies -* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transferindo arquivos para o cliente -* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Trabalhando com template JavaScript embutido (ejs) -* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Criando páginas de erro -* [error](https://github.com/expressjs/express/tree/master/examples/error) - Trabalhando com um middleware de erro -* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Manipulador de requisições simples -* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown como mecanismo de modelo -* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Trabalhando com vários roteadores Expressos -* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - controladores do estilo MVC -* [online](https://github.com/expressjs/express/tree/master/examples/online) - Rastreando atividade de usuário online com pacotes `online` e `redis` -* [params](https://github.com/expressjs/express/tree/master/examples/params) - Trabalhando com parâmetros de rotas -* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Várias operações HTTP no mesmo recurso -* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organização de rotas usando um mapa -* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Trabalhando com sistema de middleware -* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizando rotas por recurso -* [search](https://github.com/expressjs/express/tree/master/examples/search) - Pesquisa API -* [session](https://github.com/expressjs/express/tree/master/examples/session) - Sessões de usuário -* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Servendo arquivos estáticos -* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Trabalhando com hosts virtuais -* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Renderizando visualizações dinamicamente -* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Salvando dados no objeto da solicitação entre chamadas de middleware -* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Serviço de API simples +- [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Autenticação com login e senha +- [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - negociação de conteúdo HTTP +- [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Trabalhando com sessões baseadas em cookies +- [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Trabalhando com cookies +- [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transferindo arquivos para o cliente +- [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Trabalhando com template JavaScript embutido (ejs) +- [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Criando páginas de erro +- [error](https://github.com/expressjs/express/tree/master/examples/error) - Trabalhando com um middleware de erro +- [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Manipulador de requisições simples +- [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown como mecanismo de modelo +- [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Trabalhando com vários roteadores Expressos +- [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - controladores do estilo MVC +- [online](https://github.com/expressjs/express/tree/master/examples/online) - Rastreando atividade de usuário online com pacotes `online` e `redis` +- [params](https://github.com/expressjs/express/tree/master/examples/params) - Trabalhando com parâmetros de rotas +- [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Várias operações HTTP no mesmo recurso +- [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organização de rotas usando um mapa +- [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Trabalhando com sistema de middleware +- [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizando rotas por recurso +- [search](https://github.com/expressjs/express/tree/master/examples/search) - Pesquisa API +- [session](https://github.com/expressjs/express/tree/master/examples/session) - Sessões de usuário +- [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Servendo arquivos estáticos +- [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Trabalhando com hosts virtuais +- [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Renderizando visualizações dinamicamente +- [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Salvando dados no objeto da solicitação entre chamadas de middleware +- [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Serviço de API simples ## Exemplos adicionais @@ -45,5 +45,5 @@ Expressjs. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Aplicativo Fullstack com Express and Next.js usando [Prisma](https://www.npmjs.com/package/prisma) como ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - API REST com Express in TypeScript usando [Prisma](https://www.npmjs.com/package/prisma) como ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Aplicativo Fullstack com Express and Next.js usando [Prisma](https://www.npmjs.com/package/prisma) como ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - API REST com Express in TypeScript usando [Prisma](https://www.npmjs.com/package/prisma) como ORM diff --git a/src/content/docs/pt-br/5x/starter/generator.mdx b/src/content/docs/pt-br/5x/starter/generator.mdx index d2c4fade8e..44d8308549 100644 --- a/src/content/docs/pt-br/5x/starter/generator.mdx +++ b/src/content/docs/pt-br/5x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force força em diretório não-vazio ``` -Por exemplo, o seguinte cria um aplicativo Expresso chamado *myapp*. O aplicativo será criado em uma pasta chamada *myapp* no diretório de trabalho atual e o mecanismo de visualização será definido para Pug: +Por exemplo, o seguinte cria um aplicativo Expresso chamado _myapp_. O aplicativo será criado em uma pasta chamada _myapp_ no diretório de trabalho atual e o mecanismo de visualização será definido para Pug: ```bash $ express --view=pug meuapp @@ -105,11 +105,11 @@ package. son ── imagens ├── javascripts ├── stylesheets -── style styesheets +── style styesheets ─ style. ss ── rotas ├── index.js -─── usuarios +─── usuarios . s ── visões erros de ── . ug diff --git a/src/content/docs/pt-br/5x/starter/hello-world.mdx b/src/content/docs/pt-br/5x/starter/hello-world.mdx index 0680e55315..3410dc5564 100644 --- a/src/content/docs/pt-br/5x/starter/hello-world.mdx +++ b/src/content/docs/pt-br/5x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Embutido abaixo é essencialmente o aplicativo Expresso mais simples que você pode criar. É um único aplicativo de arquivo -— *não* o que você obteria se usar o [Express generator](/en/starter/generator), que +— _não_ o que você obteria se usar o [Express generator](/en/starter/generator), que cria o andaime para um aplicativo completo com vários arquivos JavaScript, modelos Jade e subdiretórios para vários fins. @@ -20,7 +20,7 @@ const app = express(); const port = 3000; app.get('/', (req, res) => { - res. end('Olá Mundo!'); + res.end('Olá Mundo!'); }); app.listen(port, () => { @@ -29,7 +29,7 @@ app.listen(port, () => { ``` Este aplicativo inicia um servidor e escuta na porta 3000 para conexões. O aplicativo responde com "Olá Mundo!" para solicitações -para a URL raiz (`/`) ou *route*. Para todos os outros caminhos, responderá com um **404 Não Encontrado**. +para a URL raiz (`/`) ou _route_. Para todos os outros caminhos, responderá com um **404 Não Encontrado**. ## Executando localmente diff --git a/src/content/docs/zh-tw/4x/guide/behind-proxies.mdx b/src/content/docs/zh-tw/4x/guide/behind-proxies.mdx index dc509998f7..d96970dd67 100644 --- a/src/content/docs/zh-tw/4x/guide/behind-proxies.mdx +++ b/src/content/docs/zh-tw/4x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ When setting to `true`, it is important to ensure that the last reverse proxy tr An IP address, subnet, or an array of IP addresses and subnets to trust as being a reverse proxy. The following list shows the pre-configured subnet names: -* loopback - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` You can set IP addresses in any of the following ways: diff --git a/src/content/docs/zh-tw/4x/guide/error-handling.mdx b/src/content/docs/zh-tw/4x/guide/error-handling.mdx index 78f1c86e92..e34218f841 100644 --- a/src/content/docs/zh-tw/4x/guide/error-handling.mdx +++ b/src/content/docs/zh-tw/4x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Understand how Express.js handles errors in synchronous and asynchr import Alert from '@components/primitives/Alert/Alert.astro'; -*Error Handling* refers to how Express catches and processes errors that +_Error Handling_ refers to how Express catches and processes errors that occur both synchronously and asynchronously. Express comes with a default error handler so you don't need to write your own to get started. @@ -161,12 +161,12 @@ Set the environment variable `NODE_ENV` to `production`, to run the app in produ When an error is written, the following information is added to the response: -* The `res.statusCode` is set from `err.status` (or `err.statusCode`). If +- The `res.statusCode` is set from `err.status` (or `err.statusCode`). If this value is outside the 4xx or 5xx range, it will be set to 500. -* The `res.statusMessage` is set according to the status code. -* The body will be the HTML of the status code message when in production +- The `res.statusMessage` is set according to the status code. +- The body will be the HTML of the status code message when in production environment, otherwise will be `err.stack`. -* Any headers specified in an `err.headers` object. +- Any headers specified in an `err.headers` object. If you call `next()` with an error after you have started writing the response (for example, if you encounter an error while streaming the @@ -258,7 +258,7 @@ function logErrors(err, req, res, next) { Also in this example, `clientErrorHandler` is defined as follows; in this case, the error is explicitly passed along to the next one. -Notice that when *not* calling "next" in an error-handling function, you are responsible for writing (and ending) the response. Otherwise, those requests will "hang" and will not be eligible for garbage collection. +Notice that when _not_ calling "next" in an error-handling function, you are responsible for writing (and ending) the response. Otherwise, those requests will "hang" and will not be eligible for garbage collection. ```js function clientErrorHandler(err, req, res, next) { diff --git a/src/content/docs/zh-tw/4x/guide/routing.mdx b/src/content/docs/zh-tw/4x/guide/routing.mdx index 78ab64f6e8..930e7b8438 100644 --- a/src/content/docs/zh-tw/4x/guide/routing.mdx +++ b/src/content/docs/zh-tw/4x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Learn how to define and use routes in Express.js applications, incl import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* refers to how an application's endpoints (URIs) respond to client requests. +_Routing_ refers to how an application's endpoints (URIs) respond to client requests. For an introduction to routing, see [Basic routing](/en/starter/basic-routing). You define routing using methods of the Express `app` object that correspond to HTTP methods; @@ -52,7 +52,7 @@ app.post('/', (req, res) => { Express supports methods that correspond to all HTTP request methods: `get`, `post`, and so on. For a full list, see [app.METHOD](/en/5x/api#app.METHOD). -There is a special routing method, `app.all()`, used to load middleware functions at a path for *all* HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). +There is a special routing method, `app.all()`, used to load middleware functions at a path for _all_ HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { In this example: -* `GET /user/5` → handled by first route → sends "User 5" -* `GET /user/0` → first route calls `next('route')`, skipping to the next matching `/user/:id` route +- `GET /user/5` → handled by first route → sends "User 5" +- `GET /user/0` → first route calls `next('route')`, skipping to the next matching `/user/:id` route Route handlers can be in the form of a function, an array of functions, or combinations of both, as shown in the following examples. diff --git a/src/content/docs/zh-tw/4x/guide/using-middleware.mdx b/src/content/docs/zh-tw/4x/guide/using-middleware.mdx index 026542a234..36f8034ef2 100644 --- a/src/content/docs/zh-tw/4x/guide/using-middleware.mdx +++ b/src/content/docs/zh-tw/4x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express is a routing and middleware web framework that has minimal functionality of its own: An Express application is essentially a series of middleware function calls. -*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. +_Middleware_ functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. Middleware functions can perform the following tasks: -* Execute any code. -* Make changes to the request and the response objects. -* End the request-response cycle. -* Call the next middleware function in the stack. +- Execute any code. +- Make changes to the request and the response objects. +- End the request-response cycle. +- Call the next middleware function in the stack. If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. An Express application can use the following types of middleware: -* [Application-level middleware](#middleware.application) -* [Router-level middleware](#middleware.router) -* [Error-handling middleware](#middleware.error-handling) -* [Built-in middleware](#middleware.built-in) -* [Third-party middleware](#middleware.third-party) +- [Application-level middleware](#middleware.application) +- [Router-level middleware](#middleware.router) +- [Error-handling middleware](#middleware.error-handling) +- [Built-in middleware](#middleware.built-in) +- [Third-party middleware](#middleware.third-party) You can load application-level and router-level middleware with an optional mount path. You can also load a series of middleware functions together, which creates a sub-stack of the middleware system at a mount point. @@ -246,7 +246,7 @@ app.use('/admin', router, (req, res) => { -Error-handling middleware always takes *four* arguments. You must provide four arguments to +Error-handling middleware always takes _four_ arguments. You must provide four arguments to identify it as an error-handling middleware function. Even if you don't need to use the `next` object, you must specify it to maintain the signature. Otherwise, the `next` object will be interpreted as regular middleware and will fail to handle errors. @@ -271,9 +271,9 @@ functions that were previously included with Express are now in separate modules Express has the following built-in middleware functions: -* [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. -* [express.json](/en/5x/api#express.json) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** +- [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. +- [express.json](/en/5x/api#express.json) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** ## Third-party middleware diff --git a/src/content/docs/zh-tw/4x/guide/using-template-engines.mdx b/src/content/docs/zh-tw/4x/guide/using-template-engines.mdx index 7095bc6dd5..31edcdde82 100644 --- a/src/content/docs/zh-tw/4x/guide/using-template-engines.mdx +++ b/src/content/docs/zh-tw/4x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Discover how to integrate and use template engines like Pug, Handle import Alert from '@components/primitives/Alert/Alert.astro'; -A *template engine* enables you to use static template files in your application. At runtime, the template engine replaces +A _template engine_ enables you to use static template files in your application. At runtime, the template engine replaces variables in a template file with actual values, and transforms the template into an HTML file sent to the client. This approach makes it easier to design an HTML page. @@ -13,9 +13,9 @@ The [Express application generator](/en/starter/generator) uses [Pug](https://pu To render template files, set the following [application setting properties](/en/4x/api#app.set), in the default `app.js` created by the generator: -* `views`, the directory where the template files are located. Eg: `app.set('views', './views')`. +- `views`, the directory where the template files are located. Eg: `app.set('views', './views')`. This defaults to the `views` directory in the application root directory. -* `view engine`, the template engine to use. For example, to use the Pug template engine: `app.set('view engine', 'pug')`. +- `view engine`, the template engine to use. For example, to use the Pug template engine: `app.set('view engine', 'pug')`. Then install the corresponding template engine npm package; for example to install Pug: diff --git a/src/content/docs/zh-tw/4x/guide/writing-middleware.mdx b/src/content/docs/zh-tw/4x/guide/writing-middleware.mdx index 355028e8b0..3849cfe1fa 100644 --- a/src/content/docs/zh-tw/4x/guide/writing-middleware.mdx +++ b/src/content/docs/zh-tw/4x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Learn how to write custom middleware functions for Express.js appli import Alert from '@components/primitives/Alert/Alert.astro'; -*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. +_Middleware_ functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. Middleware functions can perform the following tasks: -* Execute any code. -* Make changes to the request and the response objects. -* End the request-response cycle. -* Call the next middleware in the stack. +- Execute any code. +- Make changes to the request and the response objects. +- End the request-response cycle. +- Call the next middleware in the stack. If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. diff --git a/src/content/docs/zh-tw/4x/starter/basic-routing.mdx b/src/content/docs/zh-tw/4x/starter/basic-routing.mdx index 35d674808b..73c12f3893 100644 --- a/src/content/docs/zh-tw/4x/starter/basic-routing.mdx +++ b/src/content/docs/zh-tw/4x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Learn the fundamentals of routing in Express.js applications, inclu import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). +_Routing_ refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). Each route can have one or more handler functions, which are executed when the route is matched. @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); Where: -* `app` is an instance of `express`. -* `METHOD` is an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in lowercase. -* `PATH` is a path on the server. -* `HANDLER` is the function executed when the route is matched. +- `app` is an instance of `express`. +- `METHOD` is an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in lowercase. +- `PATH` is a path on the server. +- `HANDLER` is the function executed when the route is matched. diff --git a/src/content/docs/zh-tw/4x/starter/examples.mdx b/src/content/docs/zh-tw/4x/starter/examples.mdx index 4135b751cd..6685b9cbe4 100644 --- a/src/content/docs/zh-tw/4x/starter/examples.mdx +++ b/src/content/docs/zh-tw/4x/starter/examples.mdx @@ -5,31 +5,31 @@ description: Explore a collection of Express.js application examples covering va import Alert from '@components/primitives/Alert/Alert.astro'; -* [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Authentication with login and password -* [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - HTTP content negotiation -* [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Working with cookie-based sessions -* [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Working with cookies -* [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transferring files to client -* [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Working with Embedded JavaScript templating (ejs) -* [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Creating error pages -* [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Working with error middleware -* [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Simple request handler -* [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown as template engine -* [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Working with multiple Express routers -* [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - MVC-style controllers -* [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Tracking online user activity with `online` and `redis` packages -* [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Working with route parameters -* [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Multiple HTTP operations on the same resource -* [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organizing routes using a map -* [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Working with route middleware -* [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizing routes per each resource -* [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Search API -* [session](https://github.com/expressjs/express/tree/4.x/examples/session) - User sessions -* [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Serving static files -* [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Working with virtual hosts -* [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Rendering views dynamically -* [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Saving data in request object between middleware calls -* [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Simple API service +- [auth](https://github.com/expressjs/express/tree/4.x/examples/auth) - Authentication with login and password +- [content-negotiation](https://github.com/expressjs/express/tree/4.x/examples/content-negotiation) - HTTP content negotiation +- [cookie-sessions](https://github.com/expressjs/express/tree/4.x/examples/cookie-sessions) - Working with cookie-based sessions +- [cookies](https://github.com/expressjs/express/tree/4.x/examples/cookies) - Working with cookies +- [downloads](https://github.com/expressjs/express/tree/4.x/examples/downloads) - Transferring files to client +- [ejs](https://github.com/expressjs/express/tree/4.x/examples/ejs) - Working with Embedded JavaScript templating (ejs) +- [error-pages](https://github.com/expressjs/express/tree/4.x/examples/error-pages) - Creating error pages +- [error](https://github.com/expressjs/express/tree/4.x/examples/error) - Working with error middleware +- [hello-world](https://github.com/expressjs/express/tree/4.x/examples/hello-world) - Simple request handler +- [markdown](https://github.com/expressjs/express/tree/4.x/examples/markdown) - Markdown as template engine +- [multi-router](https://github.com/expressjs/express/tree/4.x/examples/multi-router) - Working with multiple Express routers +- [mvc](https://github.com/expressjs/express/tree/4.x/examples/mvc) - MVC-style controllers +- [online](https://github.com/expressjs/express/tree/4.x/examples/online) - Tracking online user activity with `online` and `redis` packages +- [params](https://github.com/expressjs/express/tree/4.x/examples/params) - Working with route parameters +- [resource](https://github.com/expressjs/express/tree/4.x/examples/resource) - Multiple HTTP operations on the same resource +- [route-map](https://github.com/expressjs/express/tree/4.x/examples/route-map) - Organizing routes using a map +- [route-middleware](https://github.com/expressjs/express/tree/4.x/examples/route-middleware) - Working with route middleware +- [route-separation](https://github.com/expressjs/express/tree/4.x/examples/route-separation) - Organizing routes per each resource +- [search](https://github.com/expressjs/express/tree/4.x/examples/search) - Search API +- [session](https://github.com/expressjs/express/tree/4.x/examples/session) - User sessions +- [static-files](https://github.com/expressjs/express/tree/4.x/examples/static-files) - Serving static files +- [vhost](https://github.com/expressjs/express/tree/4.x/examples/vhost) - Working with virtual hosts +- [view-constructor](https://github.com/expressjs/express/tree/4.x/examples/view-constructor) - Rendering views dynamically +- [view-locals](https://github.com/expressjs/express/tree/4.x/examples/view-locals) - Saving data in request object between middleware calls +- [web-service](https://github.com/expressjs/express/tree/4.x/examples/web-service) - Simple API service ## Additional examples @@ -41,5 +41,5 @@ These are some additional examples with more extensive integrations. Expressjs project team. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app with Express and Next.js using [Prisma](https://www.npmjs.com/package/prisma) as an ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app with Express and Next.js using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM diff --git a/src/content/docs/zh-tw/4x/starter/generator.mdx b/src/content/docs/zh-tw/4x/starter/generator.mdx index 859bec927e..4f22665f43 100644 --- a/src/content/docs/zh-tw/4x/starter/generator.mdx +++ b/src/content/docs/zh-tw/4x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force force on non-empty directory ``` -For example, the following creates an Express app named *myapp*. The app will be created in a folder named *myapp* in the current working directory and the view engine will be set to Pug: +For example, the following creates an Express app named _myapp_. The app will be created in a folder named _myapp_ in the current working directory and the view engine will be set to Pug: ```bash $ express --view=pug myapp diff --git a/src/content/docs/zh-tw/4x/starter/hello-world.mdx b/src/content/docs/zh-tw/4x/starter/hello-world.mdx index d92beecd0a..63821ba16e 100644 --- a/src/content/docs/zh-tw/4x/starter/hello-world.mdx +++ b/src/content/docs/zh-tw/4x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Embedded below is essentially the simplest Express app you can create. It is a single file app -— *not* what you'd get if you use the [Express generator](/en/starter/generator), which +— _not_ what you'd get if you use the [Express generator](/en/starter/generator), which creates the scaffolding for a full app with numerous JavaScript files, Jade templates, and sub-directories for various purposes. @@ -29,7 +29,7 @@ app.listen(port, () => { ``` This app starts a server and listens on port 3000 for connections. The app responds with "Hello World!" for requests -to the root URL (`/`) or *route*. For every other path, it will respond with a **404 Not Found**. +to the root URL (`/`) or _route_. For every other path, it will respond with a **404 Not Found**. ## Running Locally diff --git a/src/content/docs/zh-tw/5x/guide/behind-proxies.mdx b/src/content/docs/zh-tw/5x/guide/behind-proxies.mdx index dc509998f7..d96970dd67 100644 --- a/src/content/docs/zh-tw/5x/guide/behind-proxies.mdx +++ b/src/content/docs/zh-tw/5x/guide/behind-proxies.mdx @@ -37,9 +37,9 @@ When setting to `true`, it is important to ensure that the last reverse proxy tr An IP address, subnet, or an array of IP addresses and subnets to trust as being a reverse proxy. The following list shows the pre-configured subnet names: -* loopback - `127.0.0.1/8`, `::1/128` -* linklocal - `169.254.0.0/16`, `fe80::/10` -* uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` +- loopback - `127.0.0.1/8`, `::1/128` +- linklocal - `169.254.0.0/16`, `fe80::/10` +- uniquelocal - `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7` You can set IP addresses in any of the following ways: diff --git a/src/content/docs/zh-tw/5x/guide/error-handling.mdx b/src/content/docs/zh-tw/5x/guide/error-handling.mdx index 78f1c86e92..e34218f841 100644 --- a/src/content/docs/zh-tw/5x/guide/error-handling.mdx +++ b/src/content/docs/zh-tw/5x/guide/error-handling.mdx @@ -5,7 +5,7 @@ description: Understand how Express.js handles errors in synchronous and asynchr import Alert from '@components/primitives/Alert/Alert.astro'; -*Error Handling* refers to how Express catches and processes errors that +_Error Handling_ refers to how Express catches and processes errors that occur both synchronously and asynchronously. Express comes with a default error handler so you don't need to write your own to get started. @@ -161,12 +161,12 @@ Set the environment variable `NODE_ENV` to `production`, to run the app in produ When an error is written, the following information is added to the response: -* The `res.statusCode` is set from `err.status` (or `err.statusCode`). If +- The `res.statusCode` is set from `err.status` (or `err.statusCode`). If this value is outside the 4xx or 5xx range, it will be set to 500. -* The `res.statusMessage` is set according to the status code. -* The body will be the HTML of the status code message when in production +- The `res.statusMessage` is set according to the status code. +- The body will be the HTML of the status code message when in production environment, otherwise will be `err.stack`. -* Any headers specified in an `err.headers` object. +- Any headers specified in an `err.headers` object. If you call `next()` with an error after you have started writing the response (for example, if you encounter an error while streaming the @@ -258,7 +258,7 @@ function logErrors(err, req, res, next) { Also in this example, `clientErrorHandler` is defined as follows; in this case, the error is explicitly passed along to the next one. -Notice that when *not* calling "next" in an error-handling function, you are responsible for writing (and ending) the response. Otherwise, those requests will "hang" and will not be eligible for garbage collection. +Notice that when _not_ calling "next" in an error-handling function, you are responsible for writing (and ending) the response. Otherwise, those requests will "hang" and will not be eligible for garbage collection. ```js function clientErrorHandler(err, req, res, next) { diff --git a/src/content/docs/zh-tw/5x/guide/routing.mdx b/src/content/docs/zh-tw/5x/guide/routing.mdx index 78ab64f6e8..930e7b8438 100644 --- a/src/content/docs/zh-tw/5x/guide/routing.mdx +++ b/src/content/docs/zh-tw/5x/guide/routing.mdx @@ -5,7 +5,7 @@ description: Learn how to define and use routes in Express.js applications, incl import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* refers to how an application's endpoints (URIs) respond to client requests. +_Routing_ refers to how an application's endpoints (URIs) respond to client requests. For an introduction to routing, see [Basic routing](/en/starter/basic-routing). You define routing using methods of the Express `app` object that correspond to HTTP methods; @@ -52,7 +52,7 @@ app.post('/', (req, res) => { Express supports methods that correspond to all HTTP request methods: `get`, `post`, and so on. For a full list, see [app.METHOD](/en/5x/api#app.METHOD). -There is a special routing method, `app.all()`, used to load middleware functions at a path for *all* HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). +There is a special routing method, `app.all()`, used to load middleware functions at a path for _all_ HTTP request methods. For example, the following handler is executed for requests to the route `"/secret"` whether using `GET`, `POST`, `PUT`, `DELETE`, or any other HTTP request method supported in the [http module](https://nodejs.org/api/http.html#http_http_methods). ```js app.all('/secret', (req, res, next) => { @@ -257,8 +257,8 @@ app.get('/user/:id', (req, res) => { In this example: -* `GET /user/5` → handled by first route → sends "User 5" -* `GET /user/0` → first route calls `next('route')`, skipping to the next matching `/user/:id` route +- `GET /user/5` → handled by first route → sends "User 5" +- `GET /user/0` → first route calls `next('route')`, skipping to the next matching `/user/:id` route Route handlers can be in the form of a function, an array of functions, or combinations of both, as shown in the following examples. diff --git a/src/content/docs/zh-tw/5x/guide/using-middleware.mdx b/src/content/docs/zh-tw/5x/guide/using-middleware.mdx index 026542a234..36f8034ef2 100644 --- a/src/content/docs/zh-tw/5x/guide/using-middleware.mdx +++ b/src/content/docs/zh-tw/5x/guide/using-middleware.mdx @@ -7,24 +7,24 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Express is a routing and middleware web framework that has minimal functionality of its own: An Express application is essentially a series of middleware function calls. -*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. +_Middleware_ functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the next middleware function in the application's request-response cycle. The next middleware function is commonly denoted by a variable named `next`. Middleware functions can perform the following tasks: -* Execute any code. -* Make changes to the request and the response objects. -* End the request-response cycle. -* Call the next middleware function in the stack. +- Execute any code. +- Make changes to the request and the response objects. +- End the request-response cycle. +- Call the next middleware function in the stack. If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. An Express application can use the following types of middleware: -* [Application-level middleware](#middleware.application) -* [Router-level middleware](#middleware.router) -* [Error-handling middleware](#middleware.error-handling) -* [Built-in middleware](#middleware.built-in) -* [Third-party middleware](#middleware.third-party) +- [Application-level middleware](#middleware.application) +- [Router-level middleware](#middleware.router) +- [Error-handling middleware](#middleware.error-handling) +- [Built-in middleware](#middleware.built-in) +- [Third-party middleware](#middleware.third-party) You can load application-level and router-level middleware with an optional mount path. You can also load a series of middleware functions together, which creates a sub-stack of the middleware system at a mount point. @@ -246,7 +246,7 @@ app.use('/admin', router, (req, res) => { -Error-handling middleware always takes *four* arguments. You must provide four arguments to +Error-handling middleware always takes _four_ arguments. You must provide four arguments to identify it as an error-handling middleware function. Even if you don't need to use the `next` object, you must specify it to maintain the signature. Otherwise, the `next` object will be interpreted as regular middleware and will fail to handle errors. @@ -271,9 +271,9 @@ functions that were previously included with Express are now in separate modules Express has the following built-in middleware functions: -* [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. -* [express.json](/en/5x/api#express.json) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** -* [express.urlencoded](/en/5x/api#express.urlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** +- [express.static](/en/5x/api#express.static) serves static assets such as HTML files, images, and so on. +- [express.json](/en/5x/api#express.json) parses incoming requests with JSON payloads. **NOTE: Available with Express 4.16.0+** +- [express.urlencoded](/en/5x/api#express.urlencoded) parses incoming requests with URL-encoded payloads. **NOTE: Available with Express 4.16.0+** ## Third-party middleware diff --git a/src/content/docs/zh-tw/5x/guide/using-template-engines.mdx b/src/content/docs/zh-tw/5x/guide/using-template-engines.mdx index 7095bc6dd5..31edcdde82 100644 --- a/src/content/docs/zh-tw/5x/guide/using-template-engines.mdx +++ b/src/content/docs/zh-tw/5x/guide/using-template-engines.mdx @@ -5,7 +5,7 @@ description: Discover how to integrate and use template engines like Pug, Handle import Alert from '@components/primitives/Alert/Alert.astro'; -A *template engine* enables you to use static template files in your application. At runtime, the template engine replaces +A _template engine_ enables you to use static template files in your application. At runtime, the template engine replaces variables in a template file with actual values, and transforms the template into an HTML file sent to the client. This approach makes it easier to design an HTML page. @@ -13,9 +13,9 @@ The [Express application generator](/en/starter/generator) uses [Pug](https://pu To render template files, set the following [application setting properties](/en/4x/api#app.set), in the default `app.js` created by the generator: -* `views`, the directory where the template files are located. Eg: `app.set('views', './views')`. +- `views`, the directory where the template files are located. Eg: `app.set('views', './views')`. This defaults to the `views` directory in the application root directory. -* `view engine`, the template engine to use. For example, to use the Pug template engine: `app.set('view engine', 'pug')`. +- `view engine`, the template engine to use. For example, to use the Pug template engine: `app.set('view engine', 'pug')`. Then install the corresponding template engine npm package; for example to install Pug: diff --git a/src/content/docs/zh-tw/5x/guide/writing-middleware.mdx b/src/content/docs/zh-tw/5x/guide/writing-middleware.mdx index a22cd12f84..507c3ac06a 100644 --- a/src/content/docs/zh-tw/5x/guide/writing-middleware.mdx +++ b/src/content/docs/zh-tw/5x/guide/writing-middleware.mdx @@ -5,14 +5,14 @@ description: Learn how to write custom middleware functions for Express.js appli import Alert from '@components/primitives/Alert/Alert.astro'; -*Middleware* functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. +_Middleware_ functions are functions that have access to the [request object](/en/5x/api#req) (`req`), the [response object](/en/5x/api#res) (`res`), and the `next` function in the application's request-response cycle. The `next` function is a function in the Express router which, when invoked, executes the middleware succeeding the current middleware. Middleware functions can perform the following tasks: -* Execute any code. -* Make changes to the request and the response objects. -* End the request-response cycle. -* Call the next middleware in the stack. +- Execute any code. +- Make changes to the request and the response objects. +- End the request-response cycle. +- Call the next middleware in the stack. If the current middleware function does not end the request-response cycle, it must call `next()` to pass control to the next middleware function. Otherwise, the request will be left hanging. diff --git a/src/content/docs/zh-tw/5x/starter/basic-routing.mdx b/src/content/docs/zh-tw/5x/starter/basic-routing.mdx index 35d674808b..73c12f3893 100644 --- a/src/content/docs/zh-tw/5x/starter/basic-routing.mdx +++ b/src/content/docs/zh-tw/5x/starter/basic-routing.mdx @@ -5,7 +5,7 @@ description: Learn the fundamentals of routing in Express.js applications, inclu import Alert from '@components/primitives/Alert/Alert.astro'; -*Routing* refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). +_Routing_ refers to determining how an application responds to a client request to a particular endpoint, which is a URI (or path) and a specific HTTP request method (GET, POST, and so on). Each route can have one or more handler functions, which are executed when the route is matched. @@ -17,10 +17,10 @@ app.METHOD(PATH, HANDLER); Where: -* `app` is an instance of `express`. -* `METHOD` is an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in lowercase. -* `PATH` is a path on the server. -* `HANDLER` is the function executed when the route is matched. +- `app` is an instance of `express`. +- `METHOD` is an [HTTP request method](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Methods), in lowercase. +- `PATH` is a path on the server. +- `HANDLER` is the function executed when the route is matched. diff --git a/src/content/docs/zh-tw/5x/starter/examples.mdx b/src/content/docs/zh-tw/5x/starter/examples.mdx index eccdf984c2..69f410e908 100644 --- a/src/content/docs/zh-tw/5x/starter/examples.mdx +++ b/src/content/docs/zh-tw/5x/starter/examples.mdx @@ -7,31 +7,31 @@ import Alert from '@components/primitives/Alert/Alert.astro'; This page contains list of examples using Express. -* [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Authentication with login and password -* [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - HTTP content negotiation -* [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Working with cookie-based sessions -* [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Working with cookies -* [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transferring files to client -* [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Working with Embedded JavaScript templating (ejs) -* [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Creating error pages -* [error](https://github.com/expressjs/express/tree/master/examples/error) - Working with error middleware -* [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Simple request handler -* [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown as template engine -* [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Working with multiple Express routers -* [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - MVC-style controllers -* [online](https://github.com/expressjs/express/tree/master/examples/online) - Tracking online user activity with `online` and `redis` packages -* [params](https://github.com/expressjs/express/tree/master/examples/params) - Working with route parameters -* [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Multiple HTTP operations on the same resource -* [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organizing routes using a map -* [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Working with route middleware -* [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizing routes per each resource -* [search](https://github.com/expressjs/express/tree/master/examples/search) - Search API -* [session](https://github.com/expressjs/express/tree/master/examples/session) - User sessions -* [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Serving static files -* [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Working with virtual hosts -* [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Rendering views dynamically -* [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Saving data in request object between middleware calls -* [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Simple API service +- [auth](https://github.com/expressjs/express/tree/master/examples/auth) - Authentication with login and password +- [content-negotiation](https://github.com/expressjs/express/tree/master/examples/content-negotiation) - HTTP content negotiation +- [cookie-sessions](https://github.com/expressjs/express/tree/master/examples/cookie-sessions) - Working with cookie-based sessions +- [cookies](https://github.com/expressjs/express/tree/master/examples/cookies) - Working with cookies +- [downloads](https://github.com/expressjs/express/tree/master/examples/downloads) - Transferring files to client +- [ejs](https://github.com/expressjs/express/tree/master/examples/ejs) - Working with Embedded JavaScript templating (ejs) +- [error-pages](https://github.com/expressjs/express/tree/master/examples/error-pages) - Creating error pages +- [error](https://github.com/expressjs/express/tree/master/examples/error) - Working with error middleware +- [hello-world](https://github.com/expressjs/express/tree/master/examples/hello-world) - Simple request handler +- [markdown](https://github.com/expressjs/express/tree/master/examples/markdown) - Markdown as template engine +- [multi-router](https://github.com/expressjs/express/tree/master/examples/multi-router) - Working with multiple Express routers +- [mvc](https://github.com/expressjs/express/tree/master/examples/mvc) - MVC-style controllers +- [online](https://github.com/expressjs/express/tree/master/examples/online) - Tracking online user activity with `online` and `redis` packages +- [params](https://github.com/expressjs/express/tree/master/examples/params) - Working with route parameters +- [resource](https://github.com/expressjs/express/tree/master/examples/resource) - Multiple HTTP operations on the same resource +- [route-map](https://github.com/expressjs/express/tree/master/examples/route-map) - Organizing routes using a map +- [route-middleware](https://github.com/expressjs/express/tree/master/examples/route-middleware) - Working with route middleware +- [route-separation](https://github.com/expressjs/express/tree/master/examples/route-separation) - Organizing routes per each resource +- [search](https://github.com/expressjs/express/tree/master/examples/search) - Search API +- [session](https://github.com/expressjs/express/tree/master/examples/session) - User sessions +- [static-files](https://github.com/expressjs/express/tree/master/examples/static-files) - Serving static files +- [vhost](https://github.com/expressjs/express/tree/master/examples/vhost) - Working with virtual hosts +- [view-constructor](https://github.com/expressjs/express/tree/master/examples/view-constructor) - Rendering views dynamically +- [view-locals](https://github.com/expressjs/express/tree/master/examples/view-locals) - Saving data in request object between middleware calls +- [web-service](https://github.com/expressjs/express/tree/master/examples/web-service) - Simple API service ## Additional examples @@ -45,5 +45,5 @@ Expressjs project team. -* [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app with Express and Next.js using [Prisma](https://www.npmjs.com/package/prisma) as an ORM -* [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +- [prisma-fullstack](https://github.com/prisma/prisma-examples/tree/latest/pulse/fullstack-simple-chat) - Fullstack app with Express and Next.js using [Prisma](https://www.npmjs.com/package/prisma) as an ORM +- [prisma-rest-api-ts](https://github.com/prisma/prisma-examples/tree/latest/orm/express) - REST API with Express in TypeScript using [Prisma](https://www.npmjs.com/package/prisma) as an ORM diff --git a/src/content/docs/zh-tw/5x/starter/generator.mdx b/src/content/docs/zh-tw/5x/starter/generator.mdx index 859bec927e..4f22665f43 100644 --- a/src/content/docs/zh-tw/5x/starter/generator.mdx +++ b/src/content/docs/zh-tw/5x/starter/generator.mdx @@ -42,7 +42,7 @@ $ express -h -f, --force force on non-empty directory ``` -For example, the following creates an Express app named *myapp*. The app will be created in a folder named *myapp* in the current working directory and the view engine will be set to Pug: +For example, the following creates an Express app named _myapp_. The app will be created in a folder named _myapp_ in the current working directory and the view engine will be set to Pug: ```bash $ express --view=pug myapp diff --git a/src/content/docs/zh-tw/5x/starter/hello-world.mdx b/src/content/docs/zh-tw/5x/starter/hello-world.mdx index d92beecd0a..63821ba16e 100644 --- a/src/content/docs/zh-tw/5x/starter/hello-world.mdx +++ b/src/content/docs/zh-tw/5x/starter/hello-world.mdx @@ -8,7 +8,7 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Embedded below is essentially the simplest Express app you can create. It is a single file app -— *not* what you'd get if you use the [Express generator](/en/starter/generator), which +— _not_ what you'd get if you use the [Express generator](/en/starter/generator), which creates the scaffolding for a full app with numerous JavaScript files, Jade templates, and sub-directories for various purposes. @@ -29,7 +29,7 @@ app.listen(port, () => { ``` This app starts a server and listens on port 3000 for connections. The app responds with "Hello World!" for requests -to the root URL (`/`) or *route*. For every other path, it will respond with a **404 Not Found**. +to the root URL (`/`) or _route_. For every other path, it will respond with a **404 Not Found**. ## Running Locally diff --git a/src/content/pages/de/advanced/best-practice-security.mdx b/src/content/pages/de/advanced/best-practice-security.mdx index a9967fe49c..08ecbd91ab 100644 --- a/src/content/pages/de/advanced/best-practice-security.mdx +++ b/src/content/pages/de/advanced/best-practice-security.mdx @@ -1,11 +1,11 @@ --- -title: "Beste Produktionspraktiken: Sicherheit" +title: 'Beste Produktionspraktiken: Sicherheit' description: Entdecken Sie wichtige Sicherheits-Best Practices für Express-Apps in der Produktion, einschließlich der Verwendung von TLS, Eingabe-Validierung, sichere Cookies und der Vermeidung von Schwachstellen. --- import Alert from '@components/primitives/Alert/Alert.astro'; -Der Begriff *"production"* bezieht sich auf die Stufe im Software-Lebenszyklus, wenn eine Anwendung oder API allgemein für Endbenutzer oder Verbraucher verfügbar ist. Im Gegensatz dazu, in der *"development"* Bühne, Sie immer noch aktiv schreiben und Test-Code, und die Anwendung ist nicht offen für externen Zugriff. Die entsprechenden Systemumgebungen werden als *production* bzw. *development* Umgebungen bezeichnet. +Der Begriff _"production"_ bezieht sich auf die Stufe im Software-Lebenszyklus, wenn eine Anwendung oder API allgemein für Endbenutzer oder Verbraucher verfügbar ist. Im Gegensatz dazu, in der _"development"_ Bühne, Sie immer noch aktiv schreiben und Test-Code, und die Anwendung ist nicht offen für externen Zugriff. Die entsprechenden Systemumgebungen werden als _production_ bzw. _development_ Umgebungen bezeichnet. Entwicklungs- und Produktionsumgebungen sind in der Regel unterschiedlich aufgebaut und haben sehr unterschiedliche Anforderungen. Was in der Entwicklung gut ist, kann in der Produktion nicht akzeptabel sein. In einer Entwicklungsumgebung könnte es sein, dass Sie ausführliche Protokollierung von Fehlern zum Debuggen wünschen während das gleiche Verhalten kann zu einem Sicherheitsbedenken in einer Produktionsumgebung werden. Und in der Entwicklung müssen Sie sich keine Sorgen um Skalierbarkeit, Zuverlässigkeit und Leistung machen, während diese Bedenken in der Produktion entscheidend werden. @@ -18,21 +18,21 @@ Richtlinien und Prozeduren. Best Practices für Express-Anwendungen in der Produktion beinhalten: -* [Beste Produktionspraktiken: Sicherheit](#production-best-practices-security) - * [Overview](#overview) - * [Veraltete oder verwundbare Versionen von Express](#dont-use-deprecated-or-vulnerable-versions-of-express) - * [Benutze TLS](#use-tls) - * [Nicht auf Benutzereingabe vertrauen](#do-not-trust-user-input) - * [Verhindere offene Weiterleitungen](#prevent-open-redirects) - * [Helm verwenden](#use-helmet) - * [Fingerabdruck reduzieren](#reduce-fingerprinting) - * [Cookies sicher verwenden](#use-cookies-securely) - * [Benutze nicht den Standard-Sitzungs-Cookie Name](#dont-use-the-default-session-cookie-name) - * [Cookie Sicherheitseinstellungen setzen](#set-cookie-security-options) - * [Verhindere Brute-Force-Angriffe gegen Autorisierung](#prevent-brute-force-attacks-against-authorization) - * [Vergewissern Sie sich, dass Ihre Abhängigkeiten sicher sind](#ensure-your-dependencies-are-secure) - * [Vermeide andere bekannte Schwachstellen aus](#avoid-other-known-vulnerabilities) - * [Zusätzliche Überlegungen](#additional-considerations) +- [Beste Produktionspraktiken: Sicherheit](#production-best-practices-security) + - [Overview](#overview) + - [Veraltete oder verwundbare Versionen von Express](#dont-use-deprecated-or-vulnerable-versions-of-express) + - [Benutze TLS](#use-tls) + - [Nicht auf Benutzereingabe vertrauen](#do-not-trust-user-input) + - [Verhindere offene Weiterleitungen](#prevent-open-redirects) + - [Helm verwenden](#use-helmet) + - [Fingerabdruck reduzieren](#reduce-fingerprinting) + - [Cookies sicher verwenden](#use-cookies-securely) + - [Benutze nicht den Standard-Sitzungs-Cookie Name](#dont-use-the-default-session-cookie-name) + - [Cookie Sicherheitseinstellungen setzen](#set-cookie-security-options) + - [Verhindere Brute-Force-Angriffe gegen Autorisierung](#prevent-brute-force-attacks-against-authorization) + - [Vergewissern Sie sich, dass Ihre Abhängigkeiten sicher sind](#ensure-your-dependencies-are-secure) + - [Vermeide andere bekannte Schwachstellen aus](#avoid-other-known-vulnerabilities) + - [Zusätzliche Überlegungen](#additional-considerations) ## Veraltete oder verwundbare Versionen von Express nicht verwenden @@ -44,7 +44,7 @@ Vergewissern Sie sich auch, dass Sie keine der verwundbaren Express-Versionen au Wenn Ihre App sensible Daten behandelt oder übermittelt, verwenden Sie [Transport-Layer-Sicherheit](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) um die Verbindung und die Daten zu sichern. Diese Technologie verschlüsselt Daten, bevor sie vom Client an den Server gesendet werden, und verhindert so einige häufige (und einfache) Hacks. Obwohl Ajax und POST Anfragen möglicherweise nicht sichtbar sind und im Browser "versteckt" zu sein scheinen, ihr Netzwerkverkehr ist anfällig für [Paket-Sniffing](https://en.wikipedia.org/wiki/Packet_analyzer) und [Man-in-the-middle-Angriffe](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). -Sie können mit der Verschlüsselung Secure Socket Layer (SSL) vertraut sein. [TLS ist einfach die nächste Weiterentwicklung von SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). Mit anderen Worten: Wenn Sie SSL zuvor verwendet haben, sollten Sie ein Upgrade auf TLS in Betracht ziehen. Im Allgemeinen empfehlen wir Nginx mit TLS umzugehen. Für eine gute Referenz zum Konfigurieren von TLS auf Nginx (und anderen Servern) siehe [Empfohlene Server-Konfigurationen (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). +Sie können mit der Verschlüsselung Secure Socket Layer (SSL) vertraut sein. [TLS ist einfach die nächste Weiterentwicklung von SSL](). Mit anderen Worten: Wenn Sie SSL zuvor verwendet haben, sollten Sie ein Upgrade auf TLS in Betracht ziehen. Im Allgemeinen empfehlen wir Nginx mit TLS umzugehen. Für eine gute Referenz zum Konfigurieren von TLS auf Nginx (und anderen Servern) siehe [Empfohlene Server-Konfigurationen (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). Ein praktisches Werkzeug, um ein kostenloses TLS-Zertifikat zu erhalten, ist [Let's Encrypt](https://letsencrypt.org/about/), ein kostenloses und automatisiertes TLS-Zertifikat und offene Zertifizierungsstelle (CA) zur Verfügung gestellt von der [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). @@ -55,7 +55,7 @@ Letztlich liegt die Verantwortung für die Validierung und korrekte Handhabung d ### Offene Weiterleitungen verhindern -Ein Beispiel für potenziell gefährliche Benutzereingaben ist eine *open redirect*, wo eine Anwendung akzeptiert eine URL als Benutzereingabe (oft in der URL-Abfrage, zum Beispiel "? rl=https://Beispiel. om`) und verwendet `res.redirect`um den`location\` Header und +Ein Beispiel für potenziell gefährliche Benutzereingaben ist eine _open redirect_, wo eine Anwendung akzeptiert eine URL als Benutzereingabe (oft in der URL-Abfrage, zum Beispiel "? rl=https://Beispiel. om`) und verwendet `res.redirect`um den`location\` Header und einen 3xx Status zu setzen. Eine Anwendung muss überprüfen, dass sie eine Umleitung auf die eingehende URL unterstützt, um zu vermeiden, dass Benutzer an böswillige Links wie Phishing-Websites geschickt werden unter anderem Risiken. @@ -65,11 +65,11 @@ Hier ist ein Beispiel für die Überprüfung von URLs, bevor `res.redirect` oder ```js app.use((req, res) => { try { - if (new Url(req. uery.url).host !== 'example.com') { - return res.status(400). nd(`Nicht unterstützte Weiterleitung zum Host: ${req.query.url}`); + if (new Url(req.uery.url).host !== 'example.com') { + return res.status(400).nd(`Nicht unterstützte Weiterleitung zum Host: ${req.query.url}`); } } catch (e) { - return res. tatus(400).end(`Ungültige Url: ${req.query.url}`); + return res.tatus(400).end(`Ungültige Url: ${req.query.url}`); } res.redirect(req.query.url); }); @@ -81,19 +81,19 @@ app.use((req, res) => { Helmet ist eine Middleware-Funktion, die sicherheitsrelevante HTTP-Antwort-Header festlegt. Helm setzt standardmäßig folgende Kopfzeilen: -* `Content-Security-Policy`: Eine mächtige Zulassungsliste dessen, was auf deiner Seite passieren kann, die viele Angriffe mildert -* `Cross-Origin-Opener-Policy`: Hilft dabei, Ihre Seite zu isolieren -* `Cross-Origin-Resource-Policy`: Blockiert andere vom Laden deiner Ressourcen Cross-origin -* `Origin-Agent-Cluster`: Ändert die Prozess-Isolation in originalbasierte -* `Referrer-Policy`: Steuert den [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) Header -* "Strict-Transport-Sicherheit": Bedeutet Browser, HTTPS vorzuziehen -* `X-Content-Type-Optionen`: Vermeiden [MIME Sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) -* `X-DNS-Prefetch-Control`: Steuert DNS-Vorabholung -* `X-Download-Optionen`: Erzwingt Downloads zu speichern (nur im Internet Explorer) -* `X-Frame-Optionen`: Legacy-Header, der [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) Angriffe mildert -* `X-Permitted-Cross-Domain-Policies`: Kontrolliert Domainübergreifendes Verhalten für Adobe-Produkte wie Acrobat -* `X-Powered-By`: Info über den Webserver. Entfernt, weil es bei einfachen Angriffen verwendet werden kann -* `X-XSS-Protection`: Legacy-Header, der versucht, [XSS-Angriffs](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), zu mildern, aber die Dinge verschlimmert, also deaktiviert Helm ihn +- `Content-Security-Policy`: Eine mächtige Zulassungsliste dessen, was auf deiner Seite passieren kann, die viele Angriffe mildert +- `Cross-Origin-Opener-Policy`: Hilft dabei, Ihre Seite zu isolieren +- `Cross-Origin-Resource-Policy`: Blockiert andere vom Laden deiner Ressourcen Cross-origin +- `Origin-Agent-Cluster`: Ändert die Prozess-Isolation in originalbasierte +- `Referrer-Policy`: Steuert den [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) Header +- "Strict-Transport-Sicherheit": Bedeutet Browser, HTTPS vorzuziehen +- `X-Content-Type-Optionen`: Vermeiden [MIME Sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +- `X-DNS-Prefetch-Control`: Steuert DNS-Vorabholung +- `X-Download-Optionen`: Erzwingt Downloads zu speichern (nur im Internet Explorer) +- `X-Frame-Optionen`: Legacy-Header, der [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) Angriffe mildert +- `X-Permitted-Cross-Domain-Policies`: Kontrolliert Domainübergreifendes Verhalten für Adobe-Produkte wie Acrobat +- `X-Powered-By`: Info über den Webserver. Entfernt, weil es bei einfachen Angriffen verwendet werden kann +- `X-XSS-Protection`: Legacy-Header, der versucht, [XSS-Angriffs](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), zu mildern, aber die Dinge verschlimmert, also deaktiviert Helm ihn Jeder Header kann konfiguriert oder deaktiviert werden. Um mehr darüber zu erfahren, gehen Sie bitte auf [seine Dokumentations-Website][helmet]. @@ -164,8 +164,8 @@ Um sicherzustellen, dass Cookies nicht Ihre App zum Ausnutzen öffnen, verwenden Es gibt zwei zentrale Middleware-Cookie-Sitzungsmodule: -* [express-session](https://www.npmjs.com/package/express-session), die `express.session` Middleware in Express 3.x ersetzt. -* [cookie-session](https://www.npmjs.com/package/cookie-session), die die in Express 3.x integrierte Middleware `express.cookieSession` ersetzt. +- [express-session](https://www.npmjs.com/package/express-session), die `express.session` Middleware in Express 3.x ersetzt. +- [cookie-session](https://www.npmjs.com/package/cookie-session), die die in Express 3.x integrierte Middleware `express.cookieSession` ersetzt. Der Hauptunterschied zwischen diesen beiden Modulen liegt darin, wie sie Cookie-Sitzungsdaten speichern. Die [express-session](https://www.npmjs.com/package/express-session) Middleware speichert Sitzungsdaten auf dem Server; sie speichert die Session-ID nur im Cookie selbst, nicht im Sitzungsdatum. Standardmäßig verwendet er Speicher im Speicher und ist nicht für eine Produktionsumgebung konzipiert. In der Produktion müssen Sie einen skalierbaren Session-Shop einrichten; siehe die Liste der [kompatiblen Session-Shops](https://github.com/expressjs/session#compatible-session-stores). @@ -180,7 +180,7 @@ Um dieses Problem zu vermeiden, verwenden Sie generische Cookie-Namen; zum Beisp ```js const session = require('express-session'); app.set('trust proxy', 1); // trust first proxy -app. se( +app.se( session({ secret: 's3Cur3', Name: 'sessionId', @@ -192,11 +192,11 @@ app. se( Legen Sie die folgenden Cookie-Optionen fest, um die Sicherheit zu verbessern: -* `secure` - Stellt sicher, dass der Browser das Cookie nur über HTTPS sendet. -* `httpOnly` - Stellt sicher, dass das Cookie nur über HTTP(S), nicht über Client-JavaScript, gesendet wird. Dies hilft beim Schutz vor Site-übergreifenden Skripting-Attacken. -* `domain` - gibt die Domain des Cookie an; verwenden Sie sie um sie mit der Domain des Servers zu vergleichen, auf dem die URL angefordert wird. Wenn sie übereinstimmen, überprüfen Sie als nächstes das Pfad-Attribut. -* `path` - zeigt den Pfad des Cookie; verwenden Sie ihn um mit dem Abfragepfad zu vergleichen. Wenn dies und Domäne übereinstimmen, dann senden Sie das Cookie in der Anfrage. -* `expires` - verwenden Sie, um das Ablaufdatum für persistente Cookies festzulegen. +- `secure` - Stellt sicher, dass der Browser das Cookie nur über HTTPS sendet. +- `httpOnly` - Stellt sicher, dass das Cookie nur über HTTP(S), nicht über Client-JavaScript, gesendet wird. Dies hilft beim Schutz vor Site-übergreifenden Skripting-Attacken. +- `domain` - gibt die Domain des Cookie an; verwenden Sie sie um sie mit der Domain des Servers zu vergleichen, auf dem die URL angefordert wird. Wenn sie übereinstimmen, überprüfen Sie als nächstes das Pfad-Attribut. +- `path` - zeigt den Pfad des Cookie; verwenden Sie ihn um mit dem Abfragepfad zu vergleichen. Wenn dies und Domäne übereinstimmen, dann senden Sie das Cookie in der Anfrage. +- `expires` - verwenden Sie, um das Ablaufdatum für persistente Cookies festzulegen. Hier ist ein Beispiel mit [cookie-session](https://www.npmjs.com/package/cookie-session) Middleware: @@ -267,10 +267,10 @@ Schließlich können Express-Apps—wie alle anderen Web-Apps—anfälli Hier sind einige weitere Empfehlungen der ausgezeichneten [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/). Empfehlen Sie diesen Blog-Beitrag für alle Details zu diesen Empfehlungen: -* Immer die Benutzereingabe filtern und bereinigen, um gegen Site-übergreifendes Skripting (XSS) und Injektionsangriffe zu schützen. -* Verteidigen Sie gegen SQL-Injektionsangriffe durch parametrierte Abfragen oder vorbereitete Anweisungen. -* Benutzen Sie das Open-Source [sqlmap](http://sqlmap.org/) Werkzeug, um Verwundbarkeiten in Ihrer App zu erkennen. -* Verwenden Sie die Werkzeuge [nmap](https://nmap.org/) und [sslyze](https://github.com/nabla-c0d3/sslyze) um die Konfiguration Ihrer SSL-Chiffren zu testen, Schlüssel, Neuverhandlung sowie die Gültigkeit Ihres Zertifikats. -* Verwende [safe-regex](https://www.npmjs.com/package/safe-regex), um sicherzustellen, dass deine regulären Ausdrücke nicht anfällig für [reguläre Ausdrucksverweigerung des Dienstes](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) Angriffe sind. +- Immer die Benutzereingabe filtern und bereinigen, um gegen Site-übergreifendes Skripting (XSS) und Injektionsangriffe zu schützen. +- Verteidigen Sie gegen SQL-Injektionsangriffe durch parametrierte Abfragen oder vorbereitete Anweisungen. +- Benutzen Sie das Open-Source [sqlmap](http://sqlmap.org/) Werkzeug, um Verwundbarkeiten in Ihrer App zu erkennen. +- Verwenden Sie die Werkzeuge [nmap](https://nmap.org/) und [sslyze](https://github.com/nabla-c0d3/sslyze) um die Konfiguration Ihrer SSL-Chiffren zu testen, Schlüssel, Neuverhandlung sowie die Gültigkeit Ihres Zertifikats. +- Verwende [safe-regex](https://www.npmjs.com/package/safe-regex), um sicherzustellen, dass deine regulären Ausdrücke nicht anfällig für [reguläre Ausdrucksverweigerung des Dienstes](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) Angriffe sind. [helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/de/advanced/security-updates.mdx b/src/content/pages/de/advanced/security-updates.mdx index 08350bea85..7e16278b93 100644 --- a/src/content/pages/de/advanced/security-updates.mdx +++ b/src/content/pages/de/advanced/security-updates.mdx @@ -24,42 +24,42 @@ Richtlinien und Prozeduren. ## 4,x -* 4.21.2 - * Die Abhängigkeit `path-to-regexp` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). -* 4.21.1 - * Die Abhängigkeit `cookie` wurde aktualisiert, um eine [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x) zu adressieren. Dies kann deine Anwendung beeinflussen, wenn du `res.cookie` verwendest. -* 4.20.0 - * XSS-Verwundbarkeit in `res.redirect` behoben ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). - * Die Abhängigkeit `serve-static` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/advisories/GHSA-cm22-4g7w-348p). - * Die Abhängigkeit `send` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). - * Die Abhängigkeit `path-to-regexp` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). - * Die Abhängigkeit `body-parser` wurde aktualisiert, um einen [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), dies kann deine Anwendung beeinflussen, wenn du url enconding aktiviert hast. -* 4.19.0, 4.19.1 - * Behoben der offenen Weiterleitungsverwundbarkeit in `res.location` und `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). -* 4.17.3 - * Die Abhängigkeit `qs` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/advisories/GHSA-hrpp-h998-j3pp). Dies kann Ihre Anwendung beeinflussen, wenn die folgenden APIs verwendet werden: `req.query`, `req.body`, `req.param`. -* 4.16.0 - * Die Abhängigkeit `forwarded` wurde aktualisiert, um eine [vulnerability]Adresse zu senden (https://npmjs.com/advisories/527). Dies kann Ihre Anwendung beeinflussen, wenn die folgenden APIs verwendet werden: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. - * Die Abhängigkeit `mime` wurde aktualisiert, um eine [vulnerability](https://npmjs.com/advisories/535), aber dieses Problem wirkt sich nicht auf Express aus. - * Die Abhängigkeit `send` wurde aktualisiert, um einen Schutz gegen eine [Node.js 8.5.0 Verwundbarkeit](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/) zu bieten. Dies wirkt sich nur auf die Ausführung von Express auf der speziellen Node.js Version 8.5.0 aus. -* 4.15.5 - * Die Abhängigkeit `debug` wurde aktualisiert, um eine [vulnerability](https://snyk.io/vuln/npm:debug:20170905), aber dieses Problem wirkt sich nicht auf Express aus. - * Die Abhängigkeit `fresh` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://npmjs.com/advisories/526). Dies wird deine Anwendung beeinflussen, wenn die folgenden APIs verwendet werden: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. -* 4.15.3 - * Die Abhängigkeit `ms` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://snyk.io/vuln/npm:ms:20170412). Dies kann Ihre Anwendung beeinflussen, wenn die nicht vertrauenswürdige Eingabe an die Option `maxAge` in der folgenden APIs übergeben wird: `express.static`, `res.sendfile` und `res.sendFile`. -* 4.15.2 - * Die Abhängigkeit `qs` wurde aktualisiert, um eine [vulnerability](https://snyk.io/vuln/npm:qs:20170213), aber dieses Problem wirkt sich nicht auf Express aus. Die Aktualisierung auf 4.15.2 ist eine gute Praxis, aber nicht erforderlich, um die Verwundbarkeit zu beheben. -* 4.11.1 - * Verwundbarkeit der Root-Pfad-Offenlegung in `express.static`, `res.sendfile` und `res.sendFile` behoben -* 4.10.7 - * Behoben der offenen Weiterleitungsverwundbarkeit in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 4.8.8 - * Fehlerbehebung von Verzeichnisüberschreitungen in `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). -* 4.8.4 - * Node.js 0.10 kann `fd`s in bestimmten Situationen lecken, die `express.static` und `res.sendfile` betreffen. Schädliche Anfragen könnten `fd`s zu Leck führen und letztendlich zu `EMFILE` Fehlern und Serverunreaktion. -* 4.8.0 - * Sparse Arrays mit extrem hohen Indizes im Query-String könnten dazu führen, dass der Prozess aus dem Speicher geht und der Server abstürzt. - * Extrem verschachtelte Query-String-Objekte könnten dazu führen, dass der Prozess blockiert und der Server vorübergehend nicht reagiert. +- 4.21.2 + - Die Abhängigkeit `path-to-regexp` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +- 4.21.1 + - Die Abhängigkeit `cookie` wurde aktualisiert, um eine [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x) zu adressieren. Dies kann deine Anwendung beeinflussen, wenn du `res.cookie` verwendest. +- 4.20.0 + - XSS-Verwundbarkeit in `res.redirect` behoben ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + - Die Abhängigkeit `serve-static` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/advisories/GHSA-cm22-4g7w-348p). + - Die Abhängigkeit `send` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + - Die Abhängigkeit `path-to-regexp` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + - Die Abhängigkeit `body-parser` wurde aktualisiert, um einen [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), dies kann deine Anwendung beeinflussen, wenn du url enconding aktiviert hast. +- 4.19.0, 4.19.1 + - Behoben der offenen Weiterleitungsverwundbarkeit in `res.location` und `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +- 4.17.3 + - Die Abhängigkeit `qs` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://github.com/advisories/GHSA-hrpp-h998-j3pp). Dies kann Ihre Anwendung beeinflussen, wenn die folgenden APIs verwendet werden: `req.query`, `req.body`, `req.param`. +- 4.16.0 + - Die Abhängigkeit `forwarded` wurde aktualisiert, um eine [vulnerability]Adresse zu senden (https://npmjs.com/advisories/527). Dies kann Ihre Anwendung beeinflussen, wenn die folgenden APIs verwendet werden: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + - Die Abhängigkeit `mime` wurde aktualisiert, um eine [vulnerability](https://npmjs.com/advisories/535), aber dieses Problem wirkt sich nicht auf Express aus. + - Die Abhängigkeit `send` wurde aktualisiert, um einen Schutz gegen eine [Node.js 8.5.0 Verwundbarkeit](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/) zu bieten. Dies wirkt sich nur auf die Ausführung von Express auf der speziellen Node.js Version 8.5.0 aus. +- 4.15.5 + - Die Abhängigkeit `debug` wurde aktualisiert, um eine [vulnerability](https://snyk.io/vuln/npm:debug:20170905), aber dieses Problem wirkt sich nicht auf Express aus. + - Die Abhängigkeit `fresh` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://npmjs.com/advisories/526). Dies wird deine Anwendung beeinflussen, wenn die folgenden APIs verwendet werden: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. +- 4.15.3 + - Die Abhängigkeit `ms` wurde aktualisiert, um eine [vulnerability]zu adressieren (https://snyk.io/vuln/npm:ms:20170412). Dies kann Ihre Anwendung beeinflussen, wenn die nicht vertrauenswürdige Eingabe an die Option `maxAge` in der folgenden APIs übergeben wird: `express.static`, `res.sendfile` und `res.sendFile`. +- 4.15.2 + - Die Abhängigkeit `qs` wurde aktualisiert, um eine [vulnerability](https://snyk.io/vuln/npm:qs:20170213), aber dieses Problem wirkt sich nicht auf Express aus. Die Aktualisierung auf 4.15.2 ist eine gute Praxis, aber nicht erforderlich, um die Verwundbarkeit zu beheben. +- 4.11.1 + - Verwundbarkeit der Root-Pfad-Offenlegung in `express.static`, `res.sendfile` und `res.sendFile` behoben +- 4.10.7 + - Behoben der offenen Weiterleitungsverwundbarkeit in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 4.8.8 + - Fehlerbehebung von Verzeichnisüberschreitungen in `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +- 4.8.4 + - Node.js 0.10 kann `fd`s in bestimmten Situationen lecken, die `express.static` und `res.sendfile` betreffen. Schädliche Anfragen könnten `fd`s zu Leck führen und letztendlich zu `EMFILE` Fehlern und Serverunreaktion. +- 4.8.0 + - Sparse Arrays mit extrem hohen Indizes im Query-String könnten dazu führen, dass der Prozess aus dem Speicher geht und der Server abstürzt. + - Extrem verschachtelte Query-String-Objekte könnten dazu führen, dass der Prozess blockiert und der Server vorübergehend nicht reagiert. ## 3,x @@ -72,16 +72,16 @@ Wenn du nicht in der Lage bist nach 3.x zu aktualisieren, erwäge bitte [Kommerz -* 3.19.1 - * Verwundbarkeit der Root-Pfad-Offenlegung in `express.static`, `res.sendfile` und `res.sendFile` behoben -* 3.19.0 - * Behoben der offenen Weiterleitungsverwundbarkeit in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 3.16.10 - * Fehlerbehebung von Verzeichnisüberschreitungen in `express.static`. -* 3.16.6 - * Node.js 0.10 kann `fd`s in bestimmten Situationen lecken, die `express.static` und `res.sendfile` betreffen. Schädliche Anfragen könnten `fd`s zu Leck führen und letztendlich zu `EMFILE` Fehlern und Serverunreaktion. -* 3.16.0 - * Sparse Arrays, die extrem hohe Indizes im Query-String haben, könnten dazu führen, dass der Prozess aus dem Speicher geht und den Server abstürzt. - * Extrem verschachtelte Query-String-Objekte könnten dazu führen, dass der Prozess blockiert und der Server vorübergehend nicht reagiert. -* 3.3.0 - * Die 404-Reaktion eines nicht unterstützten Methodenversuchs war anfällig für Site-übergreifende Skripting-Attacken. +- 3.19.1 + - Verwundbarkeit der Root-Pfad-Offenlegung in `express.static`, `res.sendfile` und `res.sendFile` behoben +- 3.19.0 + - Behoben der offenen Weiterleitungsverwundbarkeit in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 3.16.10 + - Fehlerbehebung von Verzeichnisüberschreitungen in `express.static`. +- 3.16.6 + - Node.js 0.10 kann `fd`s in bestimmten Situationen lecken, die `express.static` und `res.sendfile` betreffen. Schädliche Anfragen könnten `fd`s zu Leck führen und letztendlich zu `EMFILE` Fehlern und Serverunreaktion. +- 3.16.0 + - Sparse Arrays, die extrem hohe Indizes im Query-String haben, könnten dazu führen, dass der Prozess aus dem Speicher geht und den Server abstürzt. + - Extrem verschachtelte Query-String-Objekte könnten dazu führen, dass der Prozess blockiert und der Server vorübergehend nicht reagiert. +- 3.3.0 + - Die 404-Reaktion eines nicht unterstützten Methodenversuchs war anfällig für Site-übergreifende Skripting-Attacken. diff --git a/src/content/pages/de/guide/database-integration.mdx b/src/content/pages/de/guide/database-integration.mdx index 53dacff31d..1c7a04d8d8 100644 --- a/src/content/pages/de/guide/database-integration.mdx +++ b/src/content/pages/de/guide/database-integration.mdx @@ -7,19 +7,19 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Hinzufügen der Möglichkeit, Datenbanken mit Express-Apps zu verbinden, ist nur eine Frage des Laden eines geeigneten Node.js Treibers für die Datenbank in Ihrer App. Dieses Dokument erklärt kurz wie Sie einige der beliebtesten Node.js-Module für Datenbanksysteme in Ihrer Express-App hinzufügen und nutzen: -* [Cassandra](#cassandra) -* [Couchbase](#couchbase) -* [CouchDB](#couchdb) -* [LevelDB](#leveldb) -* [MySQL](#mysql) -* [MongoDB](#mongodb) -* [Neo4j](#neo4j) -* [Oracle](#oracle) -* [PostgreSQL](#postgresql) -* [Redis](#redis) -* [SQL Server](#sql-server) -* [SQLite](#sqlite) -* [Elasticsearch](#elasticsearch) +- [Cassandra](#cassandra) +- [Couchbase](#couchbase) +- [CouchDB](#couchdb) +- [LevelDB](#leveldb) +- [MySQL](#mysql) +- [MongoDB](#mongodb) +- [Neo4j](#neo4j) +- [Oracle](#oracle) +- [PostgreSQL](#postgresql) +- [Redis](#redis) +- [SQL Server](#sql-server) +- [SQLite](#sqlite) +- [Elasticsearch](#elasticsearch) @@ -44,7 +44,7 @@ $ npm install cassandra-driver const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['localhost'] }); -client. xecute('select key from system.local', (err, result) => { +client.xecute('select key from system.local', (err, result) => { if (err) throw err; console.log(result.rows[0]); }); @@ -139,11 +139,11 @@ $ npm Level Level Level down const levelup = require('levelup'); const db = levelup('./mydb'); -db. ut('name', 'LevelUP', (err) => { +db.ut('name', 'LevelUP', (err) => { if (err) return console.log('Ooops!', err); - db. et('name', (err, value) => { - if (err) return console. og('Ooops!', err); + db.et('name', (err, value) => { + if (err) return console.og('Ooops!', err); console.log(`name=${value}`); }); @@ -164,19 +164,19 @@ $ npm install mysql ```js const mysql = require('mysql'); -const connection = mysql. reateConnection({ +const connection = mysql.reateConnection({ host: 'localhost', user: 'dbuser', Passwort: 's3kreee7', Datenbank: 'my_db', }); -Verbindung. onnect(); +Verbindung.onnect(); connection.query('SELECT 1 + 1 AS solution', (err, Zeilen, Felder) => { if (err) throw err; - console. og('Die Lösung ist: ', Zeilen[0].solution); + console.og('Die Lösung ist: ', Zeilen[0].solution); }); connection.end(); @@ -192,7 +192,7 @@ connection.end(); $ npm install mongodb ``` -### Beispiel (v2.*) +### Beispiel (v2.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -200,17 +200,17 @@ const MongoClient = require('mongodb').MongoClient; MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { if (err) throw err; - db. ollection('Säuge') + db.ollection('Säuge') .find() - . oArray((err, result) => { + .oArray((err, result) => { if (err) throw err; - console. og(Ergebnis); + console.og(Ergebnis); }); }); ``` -### Beispiel (v3.*) +### Beispiel (v3.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -218,14 +218,14 @@ const MongoClient = require('mongodb').MongoClient; MongoClient.connect('mongodb://localhost:27017/animals', (err, client) => { if (err) throw err; - const db = client. b('animals'); + const db = client.b('animals'); db.collection('Säugetier') .find() - . oArray((err, result) => { + .oArray((err, result) => { if (err) throw err; - console. og(Ergebnis); + console.og(Ergebnis); }); }); ``` @@ -246,18 +246,18 @@ $ npm install neo4j-driver ```js const neo4j = require('neo4j-driver'); -const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth. asic('neo4j', 'letmein')); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth.asic('neo4j', 'letmein')); const session = driver.session(); session.readTransaction((tx) => { return tx - . un('MATCH (n) RETURN count(n) AS count') + .un('MATCH (n) RETURN count(n) AS count') .then((res) => { - console.log(res.records[0]. et('count')); + console.log(res.records[0].et('count')); }) .catch((error) => { - Konsole. og(error); + Konsole.og(error); }); }); ``` @@ -323,12 +323,12 @@ const pgp = require('pg-promise')(/* options */); const db = pgp('postgres://username:password@host:port/database'); db.one('SELECT $1 AS value', 123) - . hen((data) => { + .hen((data) => { console.log('DATA:', data.value); }) - . atch((error) => { + .atch((error) => { console.log('ERROR:', error); -}); + }); ``` ## Redis @@ -351,15 +351,15 @@ client.on('error', (err) => { console.log(`Error ${err}`); }); -client. et('string key', 'string val', redis.print); +client.et('string key', 'string val', redis.print); client.hset('hash key', 'hashtest 1', 'some value', redis.print); -client. set(['hash key', 'hashtest 2', 'some other value'], redis.print); +client.set(['hash key', 'hashtest 2', 'some other value'], redis.print); -client. keys('hash key', (err, replies) => { +client.keys('hash key', (err, replies) => { console.log(`${replies.length} Antworten:`); - Antworten. orEach((reply, i) => { - Konsole. og(` ${i}: ${reply}`); + Antworten.orEach((reply, i) => { + Konsole.og(` ${i}: ${reply}`); }); client.quit(); @@ -480,7 +480,7 @@ const client = elasticsearch.Client({ }); client - . earch({ + .earch({ index: 'books', type: 'book', body: { @@ -492,12 +492,12 @@ client }, }, }) - . hen( + .hen( (Antwort) => { - const hits = response.hits. its; + const hits = response.hits.its; }, (error) => { - console. race(error.message); + console.race(error.message); } -); + ); ``` diff --git a/src/content/pages/de/guide/migrating-4.mdx b/src/content/pages/de/guide/migrating-4.mdx index 0c04eb75e3..28a5f90f56 100644 --- a/src/content/pages/de/guide/migrating-4.mdx +++ b/src/content/pages/de/guide/migrating-4.mdx @@ -5,7 +5,7 @@ description: Eine Anleitung zur Migration Ihrer Express.js Anwendungen von Versi import Alert from '@components/primitives/Alert/Alert.astro'; -Express 4 ist ein brillanter Wechsel von Express 3. Das bedeutet, dass eine bestehende Express 3-App *nicht* funktioniert, wenn Sie die Express-Version in ihren Abhängigkeiten aktualisieren. +Express 4 ist ein brillanter Wechsel von Express 3. Das bedeutet, dass eine bestehende Express 3-App _nicht_ funktioniert, wenn Sie die Express-Version in ihren Abhängigkeiten aktualisieren. Dieser Artikel Covers: @@ -14,7 +14,8 @@ Dieser Artikel Covers: Änderungen in Express 4.
  • - Ein Beispiel für die Migration einer Express 3 App auf Express 4. + Ein Beispiel für die Migration einer Express 3 App auf Express + 4.
  • Upgrade auf den Express 4 App-Generator. @@ -27,8 +28,9 @@ Es gibt mehrere bedeutende Änderungen in Express 4:
    • - Änderungen des Express-Core- und Middleware-Systems. Die Abhängigkeiten von - Connect und eingebauter Middleware wurden entfernt, daher müssen Sie selbst Middleware hinzufügen. + Änderungen des Express-Core- und Middleware-Systems. Die + Abhängigkeiten von Connect und eingebauter Middleware wurden entfernt, daher müssen Sie selbst + Middleware hinzufügen.
    • Änderungen am Routingsystem. @@ -40,8 +42,8 @@ Es gibt mehrere bedeutende Änderungen in Express 4: Siehe auch: -* [Neue Features in 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) -* [Migration von 3.x auf 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) +- [Neue Features in 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +- [Migration von 3.x auf 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) ### Änderungen am Express-Kern- und Middleware-System @@ -214,8 +216,8 @@ der `router` Middleware geladen wird. Die Art und Weise, wie Sie Routen definieren, ist unverändert, aber das Routensystem hat zwei neue Funktionen, um Ihre Routen zu organisieren: -* Eine neue Methode, `app.route()`, um verkettete Routenhandler für einen Routenpfad zu erstellen. -* Eine neue Klasse, `express.Router`, um modulare montierbare Routenhandler zu erstellen. +- Eine neue Methode, `app.route()`, um verkettete Routenhandler für einen Routenpfad zu erstellen. +- Eine neue Klasse, `express.Router`, um modulare montierbare Routenhandler zu erstellen. #### `app.route()` Methode @@ -297,27 +299,30 @@ Die folgende Tabelle listet weitere kleine, aber wichtige Änderungen in Express Beschreibung - Node.jsExpress 4 benötigt Node.js 0.10.x oder höher und hat die Unterstützung für Node.js 0.8.x fallen gelassen. + Node.js + + Express 4 benötigt Node.js 0.10.x oder höher und hat die Unterstützung für Node.js 0.8.x + fallen gelassen. + `http.createServer()` Das `http` Modul wird nicht mehr benötigt, außer du musst direkt mit ihm - (socket.io/SPDY/HTTPS) arbeiten. Die App kann über die Funktion `app.listen()` gestartet werden. + (socket.io/SPDY/HTTPS) arbeiten. Die App kann über die Funktion `app.listen()` gestartet + werden. `app.configure()` - Die Funktion `app.configure()` wurde entfernt. Benutze die Funktion `process.env.NODE_ENV` oder - `app.get('env')` um die Umgebung zu erkennen und die App entsprechend zu konfigurieren. + Die Funktion `app.configure()` wurde entfernt. Benutze die Funktion `process.env.NODE_ENV` + oder `app.get('env')` um die Umgebung zu erkennen und die App entsprechend zu konfigurieren. `json spaces` - - Die Eigenschaft `json spaces` ist standardmäßig in Express 4 deaktiviert. - + Die Eigenschaft `json spaces` ist standardmäßig in Express 4 deaktiviert. `req.accepted()` @@ -357,8 +362,8 @@ Die folgende Tabelle listet weitere kleine, aber wichtige Änderungen in Express `res.setHeader('Set-Cookie', val)` - Die Funktionalität ist nun auf das Setzen des grundlegenden Cookie-Wertes beschränkt. Benutze `res.cookie()` für hinzugefügte - Funktionalität. + Die Funktionalität ist nun auf das Setzen des grundlegenden Cookie-Wertes beschränkt. Benutze + `res.cookie()` für hinzugefügte Funktionalität. @@ -384,26 +389,26 @@ var path = require('path'); var app = express(); // alle Umgebungen -app. et('port', process.env.PORT || 3000); +app.et('port', process.env.PORT || 3000); app.set('views', path.join(__dirname, 'views')); app.set('view engine', 'pug'); app.use(express.favicon()); app.use(express.logger('dev')); app.use(express.methodOverride()); -app.use(express. ession({ secret: 'your secret here' })); +app.use(express.ession({ secret: 'your secret here' })); app.use(express.bodyParser()); app.use(app.router); -app.use(express. tatic(path.join(__dirname, 'public'))); +app.use(express.tatic(path.join(__dirname, 'public'))); // Entwicklung nur if (app.get('env') === 'development') { - app. se(express.errorHandler()); + app.se(express.errorHandler()); } app.get('/', routes.index); app.get('/users', user.list); -http. reateServer(app).listen(app.get('port'), () => { +http.reateServer(app).listen(app.get('port'), () => { console.log('Express Server, der auf Port ' + app.get('port')); }); ``` @@ -594,9 +599,9 @@ Express 4 Generator aktualisiert. Befehlsoptionen und -verwendung bleiben weitgehend gleich, mit den folgenden Ausnahmen: -* Die Option `--sessions` wurde entfernt. -* Die `--jshtml` Option wurde entfernt. -* `--hogan` Option hinzugefügt, um [Hogan.js]zu unterstützen (http://twitter.github.io/hogan.js/). +- Die Option `--sessions` wurde entfernt. +- Die `--jshtml` Option wurde entfernt. +- `--hogan` Option hinzugefügt, um [Hogan.js]zu unterstützen (http://twitter.github.io/hogan.js/). ### Beispiel @@ -643,7 +648,7 @@ die Zeile, die `module. xports = app;` am Ende der app.set('port', process.env.PORT || 3000); var server = app.listen(app.get('port'), () => { - debug('Express Server, der auf Port '+ server.address().port); + debug('Express Server, der auf Port ' + server.address().port); }); ``` diff --git a/src/content/pages/de/guide/migrating-5.mdx b/src/content/pages/de/guide/migrating-5.mdx index 7e243d0d03..50207306e2 100644 --- a/src/content/pages/de/guide/migrating-5.mdx +++ b/src/content/pages/de/guide/migrating-5.mdx @@ -166,7 +166,7 @@ app.del('/user/:id', (req, res) => { }); // v5 -app. elete('/user/:id', (req, res) => { +app.elete('/user/:id', (req, res) => { res.send(`DELETE /user/${req.params.id}`); }); ``` @@ -198,14 +198,14 @@ npx codemod@latest @expressjs/pluralize-method-names // v4 app.all('/', (req, res) => { req.acceptsCharset('utf-8'); - req. cceptsEncoding('br'); + req.cceptsEncoding('br'); req.acceptsLanguage('de'); // ... }); // v5 -app. ll('/', (req, res) => { +app.ll('/', (req, res) => { req.acceptsCharsets('utf-8'); req.acceptsEncodings('br'); req.acceptsLanguages('de'); @@ -237,7 +237,7 @@ npx codemod@latest @expressjs/explicit-request-params // v4 app.post('/user', (req, res) => { const id = req.param('id'); - const body = req. aram('body'); + const body = req.aram('body'); const query = req.param('query'); // ... @@ -245,7 +245,7 @@ app.post('/user', (req, res) => { // v5 app.post('/user', (req, res) => { - const id = req.params. d; + const id = req.params.d; const body = req.body; const query = req.query; @@ -273,7 +273,7 @@ app.post('/user', (req, res) => { }); // v5 -app. ost('/user', (req, res) => { +app.ost('/user', (req, res) => { res.status(201).json({ name: 'Ruben' }); }); ``` @@ -298,7 +298,7 @@ app.post('/user', (req, res) => { }); // v5 -app. ost('/user', (req, res) => { +app.ost('/user', (req, res) => { res.status(201).jsonp({ name: 'Ruben' }); }); ``` @@ -323,7 +323,7 @@ app.get('/user', (req, res) => { }); // v5 -app. et('/user', (req, res) => { +app.et('/user', (req, res) => { res.redirect(301, '/users'); }); ``` @@ -348,7 +348,7 @@ app.get('/user', (req, res) => { }); // v5 -app. et('/user', (req, res) => { +app.et('/user', (req, res) => { res.redirect(req.get('Referrer') || '/'); }); ``` @@ -373,7 +373,7 @@ app.get('/user', (req, res) => { }); // v5 -app. et('/user', (req, res) => { +app.et('/user', (req, res) => { res.status(200).send({ name: 'Ruben' }); }); ``` @@ -410,12 +410,12 @@ Die `res.sendfile()` Funktion wurde durch eine camel-cased Version `res.sendFile **Hinweis:** In Express 5, `res. endFile()` verwendet das Paket `mime-types` für MIME Typenerkennung, welches verschiedene Content-Type Werte als Express 4 für mehrere gängige Dateitypen zurückgibt: -* JavaScript-Dateien (.js): Jetzt "text/javascript" statt "application/javascript" -* JSON-Dateien (.json): jetzt "application/json" statt "text/json" -* CSS-Dateien (.css): Jetzt "text/css" statt "text/plain" -* XML-Dateien (.xml): jetzt "application/xml" statt "text/xml" -* Schriftdateien (.woff): Jetzt "font/woff" statt "application/font-woff" -* SVG-Dateien (.svg): jetzt "image/svg+xml" statt "application/svg+xml" +- JavaScript-Dateien (.js): Jetzt "text/javascript" statt "application/javascript" +- JSON-Dateien (.json): jetzt "application/json" statt "text/json" +- CSS-Dateien (.css): Jetzt "text/css" statt "text/plain" +- XML-Dateien (.xml): jetzt "application/xml" statt "text/xml" +- Schriftdateien (.woff): Jetzt "font/woff" statt "application/font-woff" +- SVG-Dateien (.svg): jetzt "image/svg+xml" statt "application/svg+xml" Sie können die veralteten Signaturen durch folgenden Befehl ersetzen: @@ -449,12 +449,12 @@ Benutze das [`mime-types` package](https://github.com/jshttp/mime-types), um mit **Wichtig:** Diese Änderung beeinflusst nicht nur die direkte Verwendung von `express.static.mime`, sondern auch andere Express-Methoden, die auf die Erkennung des MIME-Typs angewiesen sind, wie `res.sendFile()`. Die folgenden MIME-Typen haben sich von Express 4 geändert: -* JavaScript-Dateien (.js): Jetzt als "text/javascript" anstelle von "application/javascript" -* JSON-Dateien (.json): Jetzt als "application/json" anstelle von "text/json" -* CSS-Dateien (.css): Jetzt als "text/css" anstelle von "text/plain" -* HTML-Dateien (): Wird nun als "text/html; charset=utf-8" anstelle von "text/html" ausgegeben. -* XML-Dateien (.xml): Jetzt als "application/xml" anstelle von "text/xml" -* Schriftdateien (.woff): Jetzt als "font/woff" anstelle von "application/font-woff" +- JavaScript-Dateien (.js): Jetzt als "text/javascript" anstelle von "application/javascript" +- JSON-Dateien (.json): Jetzt als "application/json" anstelle von "text/json" +- CSS-Dateien (.css): Jetzt als "text/css" anstelle von "text/plain" +- HTML-Dateien (): Wird nun als "text/html; charset=utf-8" anstelle von "text/html" ausgegeben. +- XML-Dateien (.xml): Jetzt als "application/xml" anstelle von "text/xml" +- Schriftdateien (.woff): Jetzt als "font/woff" anstelle von "application/font-woff" ```js // v4 @@ -490,7 +490,7 @@ DEBUG=Express:*,router,router:* node index.js Syntax für Pfadrouten ist, wenn als erster Parameter `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()` und `router.use()` APIs angegeben wird. Die folgenden Änderungen wurden vorgenommen, wie der Pfad-String auf eine eingehende Anfrage abgestimmt wird: -* Das Platzhalter `*` muss einen Namen haben, passend zum Verhalten der Parameter `:`, verwende `/*splat` statt `/*` +- Das Platzhalter `*` muss einen Namen haben, passend zum Verhalten der Parameter `:`, verwende `/*splat` statt `/*` ```js // v4 @@ -499,7 +499,7 @@ app.get('/*', async (req, res) => { }); // v5 -app. et('/*splat', async (req, res) => { +app.et('/*splat', async (req, res) => { res.send('ok'); }); ``` @@ -516,7 +516,7 @@ app.get('/{*splat}', async (req, res) => { -* Das optionale Zeichen `?` wird nicht mehr unterstützt, verwende stattdessen Klammern. +- Das optionale Zeichen `?` wird nicht mehr unterstützt, verwende stattdessen Klammern. ```js // v4 @@ -525,12 +525,12 @@ app.get('/:file.:ext?', async (req, res) => { }); // v5 -app. et('/:file{.:ext}', async (req, res) => { +app.et('/:file{.:ext}', async (req, res) => { res.send('ok'); }); ``` -* Regexp Zeichen werden nicht unterstützt. Zum Beispiel: +- Regexp Zeichen werden nicht unterstützt. Zum Beispiel: ```js app.get('/[discussion|page]/:slug', async (req, res) => { @@ -546,8 +546,8 @@ app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { }); ``` -* Einige Zeichen wurden reserviert, um Verwirrung während des Upgrades zu vermeiden (`()[]?+!`), verwenden Sie `\` um sie zu maskieren. -* Parameternamen unterstützen nun gültige JavaScript-Identifikatoren oder zitiert wie `:"this`. +- Einige Zeichen wurden reserviert, um Verwirrung während des Upgrades zu vermeiden (`()[]?+!`), verwenden Sie `\` um sie zu maskieren. +- Parameternamen unterstützen nun gültige JavaScript-Identifikatoren oder zitiert wie `:"this`. ### Abgelehnte Versprechen von Middleware und Handlern @@ -619,7 +619,7 @@ Platzhalter (z.B. `/*splat`) erfassen Pfadsegmente als Array anstelle eines einz ```js app.get('/*splat', (req, res) => { // GET /foo/bar - console.dir(req. arams); + console.dir(req.arams); // => [Objekt: null prototype] { splat: [ 'foo', 'bar' ] } }); ``` @@ -632,21 +632,21 @@ In Express 4 waren unpassende Platzhalter leere Zeichenketten (`''`) und optiona // v4: unerreichter Platzhalter ist leerer String app.get('/*', (req, res) => { // GET / - console.dir(req. arams); + console.dir(req.arams); // => { '0': '' } }); // v4: unübertroffener optionaler Parameter ist nicht definiert -app. et('/:file.:ext?', (req, res) => { +app.et('/:file.:ext?', (req, res) => { // GET /image - Konsole. ir(req.params); + Konsole.ir(req.params); // => { file: 'image', ext: undefined } }); // v5: unmatched optional param is omitted app.get('/:file{. ext}', (req, res) => { // GET /image - console.dir(req. arams); + console.dir(req.arams); // => [Objekt: null prototype] { Datei: 'image' } }); ``` diff --git a/src/content/pages/de/resources/glossary.mdx b/src/content/pages/de/resources/glossary.mdx index 6925e982ee..90f7e204ad 100644 --- a/src/content/pages/de/resources/glossary.mdx +++ b/src/content/pages/de/resources/glossary.mdx @@ -25,9 +25,9 @@ Eine mehrplattformunabhängige Unterstützungsbibliothek, die sich auf asynchron Eine Funktion, die von der Express-Routing Layer vor dem letzten Request-Handler aufgerufen wird und sitzt somit in der Mitte zwischen einer Rohanforderung und der endgültigen geplanten Route. Ein paar schöne Terminologiepunkte rund um die Middleware: -* `var foo = require('middleware')` heißt *requiring* oder *using* ein Node.js Modul. Dann gibt die Anweisung `var mw = foo()` typischerweise die Middleware zurück. -* `app.use(mw)` heißt *adding the middleware to the global processing stack*. -* `app.get('/foo', mw, function (req, res) { ... })` heißt *adding the middleware to the "GET /foo" processing stack*. +- `var foo = require('middleware')` heißt _requiring_ oder _using_ ein Node.js Modul. Dann gibt die Anweisung `var mw = foo()` typischerweise die Middleware zurück. +- `app.use(mw)` heißt _adding the middleware to the global processing stack_. +- `app.get('/foo', mw, function (req, res) { ... })` heißt _adding the middleware to the "GET /foo" processing stack_. ### Node.js diff --git a/src/content/pages/de/resources/utils.md b/src/content/pages/de/resources/utils.md index ddac36359a..adbeba1591 100644 --- a/src/content/pages/de/resources/utils.md +++ b/src/content/pages/de/resources/utils.md @@ -8,15 +8,15 @@ description: Entdecken Sie die Utility-Module von Express.js und Node.js, einsch Die [pillarjs](https://github.com/pillarjs) GitHub Organisation enthält eine Reihe von Modulen für Utility-Funktionen, die allgemein nützlich sein können. -| Utility Module | Beschreibung | -| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Utility Module | Beschreibung | +| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [cookies](https://www.npmjs.com/package/cookies) | Erhalten und setzen Sie HTTP(S)-Cookies, die signiert werden können, um Manipulationen mit Hilfe von Keygrip zu verhindern. Kann mit der Node.js HTTP-Bibliothek oder als Express Middleware verwendet werden. | -| [csrf](https://www.npmjs.com/package/csrf) | Enthält die Logik hinter der Erstellung und Verifizierung von CSRF-Token. Verwenden Sie dieses Modul, um benutzerdefinierte CSRF Middleware zu erstellen. | -| [finalhandler](https://www.npmjs.com/package/finalhandler) | Funktion, die als letzter Schritt aufgerufen wird, um auf HTTP-Anfrage zu reagieren. | -| [parseurl](https://www.npmjs.com/package/parseurl) | Eine URL mit Cache analysieren. | -| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Verwandeln Sie einen Express-Style Pfadstring wie \`\`/user/:name\` in einen regulären Ausdruck. | -| [resolve-path](https://www.npmjs.com/package/resolve-path) | Behebt einen relativen Pfad gegen einen Wurzelpfad mit Validierung. | -| [router](https://www.npmjs.com/package/router) | Einfacher Middleware-Router. | -| [send](https://www.npmjs.com/package/send) | Bibliothek zum Streamen von Dateien als HTTP-Antwort, mit Unterstützung für partielle Antworten (Bereiche), Konditional-GET-Verhandlung und granulare Ereignisse. | +| [csrf](https://www.npmjs.com/package/csrf) | Enthält die Logik hinter der Erstellung und Verifizierung von CSRF-Token. Verwenden Sie dieses Modul, um benutzerdefinierte CSRF Middleware zu erstellen. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Funktion, die als letzter Schritt aufgerufen wird, um auf HTTP-Anfrage zu reagieren. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Eine URL mit Cache analysieren. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Verwandeln Sie einen Express-Style Pfadstring wie \`\`/user/:name\` in einen regulären Ausdruck. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Behebt einen relativen Pfad gegen einen Wurzelpfad mit Validierung. | +| [router](https://www.npmjs.com/package/router) | Einfacher Middleware-Router. | +| [send](https://www.npmjs.com/package/send) | Bibliothek zum Streamen von Dateien als HTTP-Antwort, mit Unterstützung für partielle Antworten (Bereiche), Konditional-GET-Verhandlung und granulare Ereignisse. | Weitere HTTP-basierte Module finden Sie unter [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/de/support.md b/src/content/pages/de/support.md index c93cb5a15d..9fd687be5b 100644 --- a/src/content/pages/de/support.md +++ b/src/content/pages/de/support.md @@ -7,14 +7,14 @@ Nur die neueste Version einer der wichtigsten Release-Zeilen wird unterstützt. Versionen, die EOL (Ende des Lebens) _may_ sind, erhalten Updates für kritische Sicherheitslücken, aber das Express-Team bietet keine Garantie und plant keine Korrekturen für festgestellte Probleme zu beheben oder zu veröffentlichen. -| Hauptversion | Minimale Node.js Version | Support-Startdatum | Support-Enddatum | -| ------------------------------------------- | ---------------------------------------- | ------------------ | ---------------- | -| [**v5.x**](/en/5x/api) | 18 | September 2024 | **Laufend** | -| [**v4.x**](/en/4x/api) | 0.10.0 | April 2014 | **Laufend** | -| [**v3.x**](/en/3x/api) | 0.8.0 | Oktober 2012 | Juli 2015 | -| [**v2.x**](/2x/) | 0.4.1 | März 2011 | Juli 2012 | -| **v1.x** | 0.2.0 | Dezember 2010 | März 2011 | -| **v0.14.x** | 0.1.98 | Dezember 2010 | Dezember 2010 | +| Hauptversion | Minimale Node.js Version | Support-Startdatum | Support-Enddatum | +| ---------------------- | ------------------------ | ------------------ | ---------------- | +| [**v5.x**](/en/5x/api) | 18 | September 2024 | **Laufend** | +| [**v4.x**](/en/4x/api) | 0.10.0 | April 2014 | **Laufend** | +| [**v3.x**](/en/3x/api) | 0.8.0 | Oktober 2012 | Juli 2015 | +| [**v2.x**](/2x/) | 0.4.1 | März 2011 | Juli 2012 | +| **v1.x** | 0.2.0 | Dezember 2010 | März 2011 | +| **v0.14.x** | 0.1.98 | Dezember 2010 | Dezember 2010 | ## Kommerzielle Support-Optionen diff --git a/src/content/pages/es/advanced/best-practice-security.mdx b/src/content/pages/es/advanced/best-practice-security.mdx index 4e270ab3ad..32c1f8f307 100644 --- a/src/content/pages/es/advanced/best-practice-security.mdx +++ b/src/content/pages/es/advanced/best-practice-security.mdx @@ -1,11 +1,11 @@ --- -title: "Mejores prácticas de producción: seguridad" +title: 'Mejores prácticas de producción: seguridad' description: Descubra las mejores prácticas de seguridad cruciales para aplicaciones Express en producción, incluyendo el uso de TLS, validación de entradas, cookies seguras y la prevención de vulnerabilidades. --- import Alert from '@components/primitives/Alert/Alert.astro'; -El término *"producción"* se refiere a la etapa del ciclo de vida del software cuando una aplicación o API está generalmente disponible para sus usuarios finales o consumidores. En contraste, en la etapa *"desarrollo"* todavía estás escribiendo activamente y probando código, y la aplicación no está abierta al acceso externo. Los entornos del sistema correspondientes se conocen como entornos *production* y *development*, respectivamente. +El término _"producción"_ se refiere a la etapa del ciclo de vida del software cuando una aplicación o API está generalmente disponible para sus usuarios finales o consumidores. En contraste, en la etapa _"desarrollo"_ todavía estás escribiendo activamente y probando código, y la aplicación no está abierta al acceso externo. Los entornos del sistema correspondientes se conocen como entornos _production_ y _development_, respectivamente. Los entornos de desarrollo y producción suelen establecerse de forma diferente y tienen requisitos muy diferentes. Lo que está bien en desarrollo puede no ser aceptable en la producción. Por ejemplo, en un entorno de desarrollo puede querer un registro detallado de errores para la depuración, mientras que el mismo comportamiento puede convertirse en una preocupación de seguridad en un entorno de producción. Y en desarrollo, usted no necesita preocuparse por la escalabilidad, fiabilidad y rendimiento, mientras que esas preocupaciones se vuelven críticas en la producción. @@ -18,21 +18,21 @@ Políticas y procedimientos. Las mejores prácticas de seguridad para aplicaciones Express en producción incluyen: -* [Prácticas Mejores de Producción: Seguridad](#production-best-practices-security) - * [Overview](#overview) - * [No usar versiones obsoletas o vulnerables de Express](#dont-use-deprecated-or-vulnerable-versions-of-express) - * [Usar TLS](#use-tls) - * [No confiar en la entrada del usuario](#do-not-trust-user-input) - * [Prevenir redirecciones abiertas](#prevent-open-redirects) - * [Casco de Uso](#use-helmet) - * [Reducir la huella dactilar](#reduce-fingerprinting) - * [Usar cookies de forma segura](#use-cookies-securely) - * [No usar el nombre de cookie de sesión predeterminado](#dont-use-the-default-session-cookie-name) - * [Establecer opciones de seguridad de cookies](#set-cookie-security-options) - * [Prevenir ataques de fuerza bruta contra autorización](#prevent-brute-force-attacks-against-authorization) - * [Asegúrate de que tus dependencias son seguras](#ensure-your-dependencies-are-secure) - * [Evitar otras vulnerabilidades conocidas](#avoid-other-known-vulnerabilities) - * [Examen adicional](#additional-considerations) +- [Prácticas Mejores de Producción: Seguridad](#production-best-practices-security) + - [Overview](#overview) + - [No usar versiones obsoletas o vulnerables de Express](#dont-use-deprecated-or-vulnerable-versions-of-express) + - [Usar TLS](#use-tls) + - [No confiar en la entrada del usuario](#do-not-trust-user-input) + - [Prevenir redirecciones abiertas](#prevent-open-redirects) + - [Casco de Uso](#use-helmet) + - [Reducir la huella dactilar](#reduce-fingerprinting) + - [Usar cookies de forma segura](#use-cookies-securely) + - [No usar el nombre de cookie de sesión predeterminado](#dont-use-the-default-session-cookie-name) + - [Establecer opciones de seguridad de cookies](#set-cookie-security-options) + - [Prevenir ataques de fuerza bruta contra autorización](#prevent-brute-force-attacks-against-authorization) + - [Asegúrate de que tus dependencias son seguras](#ensure-your-dependencies-are-secure) + - [Evitar otras vulnerabilidades conocidas](#avoid-other-known-vulnerabilities) + - [Examen adicional](#additional-considerations) ## No utilizar versiones obsoletas o vulnerables de Express @@ -44,7 +44,7 @@ También asegúrese de que no está usando ninguna de las versiones Express vuln Si tu aplicación trata o transmite datos confidenciales, usa [Seguridad de la capa de transporte](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) para asegurar la conexión y los datos. Esta tecnología encripta los datos antes de que sean enviados desde el cliente al servidor, evitando así algunos hacks comunes (y fáciles). Aunque las solicitudes Ajax y POST pueden no ser visiblemente obvias y parecen "ocultas" en los navegadores, su tráfico de red es vulnerable a [sniffing de paquetes](https://en.wikipedia.org/wiki/Packet_analyzer) y [ataques man-in-the-midds](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). -Puede estar familiarizado con el cifrado de la capa de conector seguro (SSL). [TLS es simplemente la siguiente progresión de SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). En otras palabras, si estaba usando SSL antes, considere actualizar a TLS. En general, recomendamos Nginx para manejar TLS. Para una buena referencia para configurar TLS en Nginx (y otros servidores), vea [Configuraciones Recomendadas del servidor (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). +Puede estar familiarizado con el cifrado de la capa de conector seguro (SSL). [TLS es simplemente la siguiente progresión de SSL](). En otras palabras, si estaba usando SSL antes, considere actualizar a TLS. En general, recomendamos Nginx para manejar TLS. Para una buena referencia para configurar TLS en Nginx (y otros servidores), vea [Configuraciones Recomendadas del servidor (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). Además, una útil herramienta para obtener un certificado TLS gratis es [Vamos a cifrar](https://letsencrypt.org/about/), un gratuito, automatizado, y autoridad certificadora abierta (CA) proporcionada por el [Grupo de Investigación sobre Seguridad de Internet (ISRG)](https://www.abetterinternet.org/). @@ -55,7 +55,7 @@ En última instancia, la responsabilidad de validar y manejar correctamente los ### Evitar redirecciones abiertas -Un ejemplo de entrada de usuario potencialmente peligrosa es una *open redirect*, donde una aplicación acepta una URL como entrada de usuario (a menudo en la consulta de URL, por ejemplo `? rl=https://ejemplo. om`) y usa `res.redirect` para establecer la cabecera `location` y +Un ejemplo de entrada de usuario potencialmente peligrosa es una _open redirect_, donde una aplicación acepta una URL como entrada de usuario (a menudo en la consulta de URL, por ejemplo `? rl=https://ejemplo. om`) y usa `res.redirect` para establecer la cabecera `location` y devuelve un estado de 3xx. Una aplicación debe validar que soporta redirección a la URL entrante para evitar enviar usuarios a enlaces maliciosos como sitios web de phishing, entre otros riesgos. @@ -81,19 +81,19 @@ app.use((req, res) => { Helmet es una función middleware que establece cabeceras de respuesta HTTP relacionadas con la seguridad. El casco establece las siguientes cabeceras por defecto: -* `Content-Security-Policy`: Una poderosa lista de permisos de lo que puede pasar en tu página que mitiga muchos ataques -* `Cross-Origin-Opener-Policy`: Ayuda a procesar su página aislada -* `Cross-Origin-Resource-Policy`: bloquea que otros carguen sus recursos de origen cruzado -* `Origin-Agent-Cluster`: Cambia el aislamiento del proceso para ser basado en el origen -* `Política de referido`: Controla el encabezado [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) -* `Strict-Transport-Security`: Indica a los navegadores que prefieran HTTPS -* `X-Content Type-Options`: Evita [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) -* `X-DNS-Prefetch-Control`: Controla la prebúsqueda DNS -* `X-Download-Options`: Fuerza a guardar las descargas (sólo Internet Explorer) -* `X-Frame-Options`: encabezado antiguo que mitiga ataques [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) -* `X-Permitted-Cross-Domain-Policies`: Controla el comportamiento entre dominios para los productos de Adobe, como Acrobat -* `X-Powered-Por`: Información sobre el servidor web. Eliminado porque puede ser usado en ataques simples -* `X-XSS-Protection`: Encabezado antiguo que intenta mitigar [Ataques XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), pero empeora las cosas, así que Helmet lo deshabilita +- `Content-Security-Policy`: Una poderosa lista de permisos de lo que puede pasar en tu página que mitiga muchos ataques +- `Cross-Origin-Opener-Policy`: Ayuda a procesar su página aislada +- `Cross-Origin-Resource-Policy`: bloquea que otros carguen sus recursos de origen cruzado +- `Origin-Agent-Cluster`: Cambia el aislamiento del proceso para ser basado en el origen +- `Política de referido`: Controla el encabezado [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) +- `Strict-Transport-Security`: Indica a los navegadores que prefieran HTTPS +- `X-Content Type-Options`: Evita [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +- `X-DNS-Prefetch-Control`: Controla la prebúsqueda DNS +- `X-Download-Options`: Fuerza a guardar las descargas (sólo Internet Explorer) +- `X-Frame-Options`: encabezado antiguo que mitiga ataques [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) +- `X-Permitted-Cross-Domain-Policies`: Controla el comportamiento entre dominios para los productos de Adobe, como Acrobat +- `X-Powered-Por`: Información sobre el servidor web. Eliminado porque puede ser usado en ataques simples +- `X-XSS-Protection`: Encabezado antiguo que intenta mitigar [Ataques XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), pero empeora las cosas, así que Helmet lo deshabilita Cada cabecera puede ser configurada o deshabilitada. Para leer más al respecto, por favor vaya a [su sitio web de documentación][helmet]. @@ -148,11 +148,11 @@ y // custom 404 app.use((req, res, next) => { - res.status(404). end("¡Lo sentimos no puede encontrar eso!"); + res.status(404).end('¡Lo sentimos no puede encontrar eso!'); }); // manejador de errores personalizado -app. se((err, req, res, next) => { +app.se((err, req, res, next) => { console.error(err.stack); res.status(500).send('Algo roto!'); }); @@ -164,8 +164,8 @@ Para asegurar que las cookies no abran su aplicación para explotar, no utilice Hay dos módulos principales de sesión de cookies de middleware: -* [express-session](https://www.npmjs.com/package/express-session) que reemplaza `express.session` middleware integrado a Express 3.x. -* [cookie-session](https://www.npmjs.com/package/cookie-session) que reemplaza el middleware `express.cookieSession` integrado a Express 3.x. +- [express-session](https://www.npmjs.com/package/express-session) que reemplaza `express.session` middleware integrado a Express 3.x. +- [cookie-session](https://www.npmjs.com/package/cookie-session) que reemplaza el middleware `express.cookieSession` integrado a Express 3.x. La principal diferencia entre estos dos módulos es cómo guardan los datos de sesión de cookies. El middleware [express-session](https://www.npmjs.com/package/express-session) almacena datos de sesión en el servidor; sólo guarda el ID de sesión en la cookie misma, no los datos de sesión. Por defecto, utiliza almacenamiento en memoria y no está diseñado para un entorno de producción. En producción, necesitarás configurar una tienda de sesiones escalable; consulta la lista de [tiendas de sesiones compatibles](https://github.com/expressjs/session#compatible-session-stores). @@ -180,7 +180,7 @@ To avoid this problem, use generic cookie names; for example using [express-sess ```js const session = require('express-session'); app.set('trust proxy', 1); // confíe en primer proxy -aplicación. se( +aplicación.se( session({ secret: 's3Cur3', name: 'sessionId', @@ -192,11 +192,11 @@ aplicación. se( Establecer las siguientes opciones de cookie para mejorar la seguridad: -* `secure` - Asegura que el navegador sólo envía la cookie a través de HTTPS. -* `httpOnly` - Asegura que la cookie se envía sólo sobre HTTP(S), no sobre JavaScript del cliente, ayudando a proteger contra ataques de cross-site scripting. -* `domain` - indica el dominio de la cookie; úselo para comparar con el dominio del servidor en el que se solicita la URL. Si coinciden, entonces marque el atributo de ruta siguiente. -* `path` - indica la ruta de la cookie; úsala para comparar la ruta de la solicitud. Si esto y el dominio coinciden, entonces envíe la cookie en la solicitud. -* `expires` - usa para fijar la fecha de caducidad de las cookies persistentes. +- `secure` - Asegura que el navegador sólo envía la cookie a través de HTTPS. +- `httpOnly` - Asegura que la cookie se envía sólo sobre HTTP(S), no sobre JavaScript del cliente, ayudando a proteger contra ataques de cross-site scripting. +- `domain` - indica el dominio de la cookie; úselo para comparar con el dominio del servidor en el que se solicita la URL. Si coinciden, entonces marque el atributo de ruta siguiente. +- `path` - indica la ruta de la cookie; úsala para comparar la ruta de la solicitud. Si esto y el dominio coinciden, entonces envíe la cookie en la solicitud. +- `expires` - usa para fijar la fecha de caducidad de las cookies persistentes. Aquí hay un ejemplo usando un middleware [cookie-session](https://www.npmjs.com/package/cookie-session): @@ -205,8 +205,8 @@ const session = require('cookie-session'); const express = require('express'); const app = express(); -const expiryDate = new Date(Date. ow() + 60 * 60 * 1000); // 1 hora -aplicación. se( +const expiryDate = new Date(Date.ow() + 60 * 60 * 1000); // 1 hora +aplicación.se( session({ name: 'session', keys: ['key1', 'key2'], @@ -267,10 +267,10 @@ Finalmente, las aplicaciones Express—como cualquier otra aplicación web&m Estas son algunas recomendaciones adicionales de la excelente [Lista de verificación de seguridad de Node.js](https://blog.risingstack.com/node-js-security-checklist/). Consulte esa entrada para ver todos los detalles de estas recomendaciones: -* Siempre filtrar y limpiar la entrada del usuario para proteger contra ataques de cross-site scripting (XSS) e inyección de comandos. -* Defienda contra ataques de inyección de SQL usando consultas parametrizadas o sentencias preparadas. -* Utilice la herramienta de código abierto [sqlmap](http://sqlmap.org/) para detectar vulnerabilidades de inyección SQL en su aplicación. -* Utilice las herramientas [nmap](https://nmap.org/) y [sslyze](https://github.com/nabla-c0d3/sslyze) para probar la configuración de sus cifrados SSL, llaves, renegociación, así como la validez de su certificado. -* Usa [safe-regex](https://www.npmjs.com/package/safe-regex) para asegurar que tus expresiones regulares no sean susceptibles a los ataques de [denegación de expresión regular de servicio](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS). +- Siempre filtrar y limpiar la entrada del usuario para proteger contra ataques de cross-site scripting (XSS) e inyección de comandos. +- Defienda contra ataques de inyección de SQL usando consultas parametrizadas o sentencias preparadas. +- Utilice la herramienta de código abierto [sqlmap](http://sqlmap.org/) para detectar vulnerabilidades de inyección SQL en su aplicación. +- Utilice las herramientas [nmap](https://nmap.org/) y [sslyze](https://github.com/nabla-c0d3/sslyze) para probar la configuración de sus cifrados SSL, llaves, renegociación, así como la validez de su certificado. +- Usa [safe-regex](https://www.npmjs.com/package/safe-regex) para asegurar que tus expresiones regulares no sean susceptibles a los ataques de [denegación de expresión regular de servicio](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS). [helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/es/advanced/security-updates.mdx b/src/content/pages/es/advanced/security-updates.mdx index afe751197e..a2b561bbff 100644 --- a/src/content/pages/es/advanced/security-updates.mdx +++ b/src/content/pages/es/advanced/security-updates.mdx @@ -24,42 +24,42 @@ Políticas y procedimientos. ## 4 x -* 4.21.2 - * La dependencia `path-to-regexp` ha sido actualizada para direccionar un [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). -* 4.21.1 - * La dependencia `cookie` ha sido actualizada para dirigirse a una [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), Esto puede afectar a tu aplicación si utilizas `res.cookie`. -* 4.20.0 - * Se corrigió la vulnerabilidad XSS en `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). - * La dependencia `serve-static` ha sido actualizada para direccionar un [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). - * La dependencia `send` ha sido actualizada para direccionar un [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). - * La dependencia `path-to-regexp` ha sido actualizada para direccionar un [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). - * La dependencia `body-parser` ha sido actualizada para montar un [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), Esto puede afectar a tu aplicación si tenías activada la conexión url. -* 4.19.0, 4.19.1 - * Corregida vulnerabilidad de redirección abierta en `res.location` y `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). -* 4.17.3 - * La dependencia `qs` ha sido actualizada para direccionar un [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). Esto puede afectar a su aplicación si se utilizan las siguientes API: `req.query`, `req.body`, `req.param`. -* 4.16.0 - * La dependencia `forwarded` ha sido actualizada para direccionar un [vulnerability](https://npmjs.com/advisories/527). Esto puede afectar a su aplicación si se utilizan las siguientes API: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. - * La dependencia `mime` ha sido actualizada para abordar un [vulnerability](https://npmjs.com/advisories/535), pero este problema no afecta a Express. - * La dependencia `send` ha sido actualizada para proporcionar una protección contra una [vulnerabilidad de Node.js 8.5.0](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). Esto sólo afecta a la ejecución de Express en la versión 8.5.0 específica de Node.js. -* 4.15.5 - * La dependencia `debug` ha sido actualizada para abordar un [vulnerability](https://snyk.io/vuln/npm:debug:20170905), pero este problema no afecta a Express. - * La dependencia `fresh` ha sido actualizada para direccionar un [vulnerability](https://npmjs.com/advisories/526). Esto afectará a tu aplicación si se utilizan las siguientes API: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. -* 4.15.3 - * La dependencia `ms` ha sido actualizada para direccionar un [vulnerability](https://snyk.io/vuln/npm:ms:20170412). Esto puede afectar a tu aplicación si la entrada de cadena no confiable es pasada a la opción `maxAge` en las siguientes APIs: `express.static`, `res.sendfile`, y `res.sendFile`. -* 4.15.2 - * La dependencia `qs` ha sido actualizada para abordar un [vulnerability](https://snyk.io/vuln/npm:qs:20170213), pero este problema no afecta a Express. Actualizar a 4.15.2 es una buena práctica, pero no es necesario para abordar la vulnerabilidad. -* 4.11.1 - * Se corrigió la vulnerabilidad de revelación de ruta de root en `express.static`, `res.sendfile`, y `res.sendFile` -* 4.10.7 - * Se corrigió la vulnerabilidad de redirección abierta en `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 4.8.8 - * Se corrigieron vulnerabilidades de recorrido de directorio en `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). -* 4.8.4 - * Node.js 0.10 puede filtrar `fd`s en ciertas situaciones que afectan `express.static` y `res.sendfile`. Las peticiones maliciosas podrían causar que `fd`s se filtrara y eventualmente llevar a `EMFILE` errores y la falta de respuesta del servidor. -* 4.8.0 - * Las matrices Sparse que tienen índices extremadamente altos en la cadena de consultas podrían causar que el proceso se quedara sin memoria y cayera el servidor. - * Los objetos de cadena de consulta anidados pueden causar que el proceso bloquee y haga que el servidor no responda temporalmente. +- 4.21.2 + - La dependencia `path-to-regexp` ha sido actualizada para direccionar un [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +- 4.21.1 + - La dependencia `cookie` ha sido actualizada para dirigirse a una [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), Esto puede afectar a tu aplicación si utilizas `res.cookie`. +- 4.20.0 + - Se corrigió la vulnerabilidad XSS en `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + - La dependencia `serve-static` ha sido actualizada para direccionar un [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). + - La dependencia `send` ha sido actualizada para direccionar un [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + - La dependencia `path-to-regexp` ha sido actualizada para direccionar un [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + - La dependencia `body-parser` ha sido actualizada para montar un [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), Esto puede afectar a tu aplicación si tenías activada la conexión url. +- 4.19.0, 4.19.1 + - Corregida vulnerabilidad de redirección abierta en `res.location` y `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +- 4.17.3 + - La dependencia `qs` ha sido actualizada para direccionar un [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). Esto puede afectar a su aplicación si se utilizan las siguientes API: `req.query`, `req.body`, `req.param`. +- 4.16.0 + - La dependencia `forwarded` ha sido actualizada para direccionar un [vulnerability](https://npmjs.com/advisories/527). Esto puede afectar a su aplicación si se utilizan las siguientes API: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + - La dependencia `mime` ha sido actualizada para abordar un [vulnerability](https://npmjs.com/advisories/535), pero este problema no afecta a Express. + - La dependencia `send` ha sido actualizada para proporcionar una protección contra una [vulnerabilidad de Node.js 8.5.0](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). Esto sólo afecta a la ejecución de Express en la versión 8.5.0 específica de Node.js. +- 4.15.5 + - La dependencia `debug` ha sido actualizada para abordar un [vulnerability](https://snyk.io/vuln/npm:debug:20170905), pero este problema no afecta a Express. + - La dependencia `fresh` ha sido actualizada para direccionar un [vulnerability](https://npmjs.com/advisories/526). Esto afectará a tu aplicación si se utilizan las siguientes API: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. +- 4.15.3 + - La dependencia `ms` ha sido actualizada para direccionar un [vulnerability](https://snyk.io/vuln/npm:ms:20170412). Esto puede afectar a tu aplicación si la entrada de cadena no confiable es pasada a la opción `maxAge` en las siguientes APIs: `express.static`, `res.sendfile`, y `res.sendFile`. +- 4.15.2 + - La dependencia `qs` ha sido actualizada para abordar un [vulnerability](https://snyk.io/vuln/npm:qs:20170213), pero este problema no afecta a Express. Actualizar a 4.15.2 es una buena práctica, pero no es necesario para abordar la vulnerabilidad. +- 4.11.1 + - Se corrigió la vulnerabilidad de revelación de ruta de root en `express.static`, `res.sendfile`, y `res.sendFile` +- 4.10.7 + - Se corrigió la vulnerabilidad de redirección abierta en `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 4.8.8 + - Se corrigieron vulnerabilidades de recorrido de directorio en `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +- 4.8.4 + - Node.js 0.10 puede filtrar `fd`s en ciertas situaciones que afectan `express.static` y `res.sendfile`. Las peticiones maliciosas podrían causar que `fd`s se filtrara y eventualmente llevar a `EMFILE` errores y la falta de respuesta del servidor. +- 4.8.0 + - Las matrices Sparse que tienen índices extremadamente altos en la cadena de consultas podrían causar que el proceso se quedara sin memoria y cayera el servidor. + - Los objetos de cadena de consulta anidados pueden causar que el proceso bloquee y haga que el servidor no responda temporalmente. ## 3.x @@ -72,16 +72,16 @@ Si no puedes actualizar más allá de 3.x, por favor considera [Opciones de Sopo -* 3.19.1 - * Se corrigió la vulnerabilidad de revelación de ruta de root en `express.static`, `res.sendfile`, y `res.sendFile` -* 3.19.0 - * Se corrigió la vulnerabilidad de redirección abierta en `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 3.16.10 - * Se corrigieron vulnerabilidades de recorrido de directorio en `express.static`. -* 3.16.6 - * Node.js 0.10 puede filtrar `fd`s en ciertas situaciones que afectan `express.static` y `res.sendfile`. Las peticiones maliciosas podrían causar que `fd`s se filtrara y eventualmente llevar a `EMFILE` errores y la falta de respuesta del servidor. -* 3.16.0 - * Las matrices Sparse que tienen índices extremadamente altos en la cadena de consultas podían causar que el proceso se quedara sin memoria y cayera el servidor. - * Los objetos de cadena de consulta anidados pueden causar que el proceso bloquee y haga que el servidor no responda temporalmente. -* 3.3.0 - * La respuesta 404 de un intento de anulación de método no soportado era susceptible a ataques de cross-site scripting. +- 3.19.1 + - Se corrigió la vulnerabilidad de revelación de ruta de root en `express.static`, `res.sendfile`, y `res.sendFile` +- 3.19.0 + - Se corrigió la vulnerabilidad de redirección abierta en `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 3.16.10 + - Se corrigieron vulnerabilidades de recorrido de directorio en `express.static`. +- 3.16.6 + - Node.js 0.10 puede filtrar `fd`s en ciertas situaciones que afectan `express.static` y `res.sendfile`. Las peticiones maliciosas podrían causar que `fd`s se filtrara y eventualmente llevar a `EMFILE` errores y la falta de respuesta del servidor. +- 3.16.0 + - Las matrices Sparse que tienen índices extremadamente altos en la cadena de consultas podían causar que el proceso se quedara sin memoria y cayera el servidor. + - Los objetos de cadena de consulta anidados pueden causar que el proceso bloquee y haga que el servidor no responda temporalmente. +- 3.3.0 + - La respuesta 404 de un intento de anulación de método no soportado era susceptible a ataques de cross-site scripting. diff --git a/src/content/pages/es/guide/database-integration.mdx b/src/content/pages/es/guide/database-integration.mdx index 7d64d12df7..6bce2faa8f 100644 --- a/src/content/pages/es/guide/database-integration.mdx +++ b/src/content/pages/es/guide/database-integration.mdx @@ -7,19 +7,19 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Añadir la capacidad para conectar bases de datos a aplicaciones Express es sólo una cuestión de cargar un controlador Node.js apropiado para la base de datos en su aplicación. Este documento explica brevemente cómo agregar y utilizar algunos de los módulos Node.js más populares para sistemas de base de datos en su aplicación Express: -* [Cassandra](#cassandra) -* [Couchbase](#couchbase) -* [CouchDB](#couchdb) -* [LevelDB](#leveldb) -* [MySQL](#mysql) -* [MongoDB](#mongodb) -* [Neo4j](#neo4j) -* [Oracle](#oracle) -* [PostgreSQL](#postgresql) -* [Redis](#redis) -* [Servidor SQL](#sql-server) -* [SQLite](#sqlite) -* [Elasticsearch](#elasticsearch) +- [Cassandra](#cassandra) +- [Couchbase](#couchbase) +- [CouchDB](#couchdb) +- [LevelDB](#leveldb) +- [MySQL](#mysql) +- [MongoDB](#mongodb) +- [Neo4j](#neo4j) +- [Oracle](#oracle) +- [PostgreSQL](#postgresql) +- [Redis](#redis) +- [Servidor SQL](#sql-server) +- [SQLite](#sqlite) +- [Elasticsearch](#elasticsearch) @@ -44,7 +44,7 @@ $ npm install cassandra-driver const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['localhost'] }); -client. xecute('select key from system.local', (err, result) => { +client.xecute('select key from system.local', (err, result) => { if (err) throw err; console.log(result.rows[0]); }); @@ -67,20 +67,20 @@ const couchbase = require('couchbase'); const bucket = new couchbase.Cluster('http://localhost:8091').openBucket('bucketName'); // añade un documento al cubo -bucket. nsert('document-key', { name: 'Matt', shoeSize: 13 }, (err, result) => { +bucket.nsert('document-key', { name: 'Matt', shoeSize: 13 }, (err, result) => { if (err) { - consola. og(err); + consola.og(err); } else { - consola. og(result); + consola.og(result); } }); // obtener todos los documentos con el tamaño de zapato 13 const n1ql = 'SELECT d. FROM `bucketName` d WHERE shoeSize = $1'; -const query = N1qlQuery. romString(n1ql); +const query = N1qlQuery.romString(n1ql); bucket.query(query, [13], (err, result) => { if (err) { - consola. og(err); + consola.og(err); } else { console.log(result); } @@ -102,21 +102,21 @@ $ npm install nano ```js const nano = require('nano')('http://localhost:5984'); nano.db.create('books'); -const books = nano.db. se('books'); +const books = nano.db.se('books'); // Inserta un documento de libro en la base de datos de libros -libros. nsert({ name: 'The Art of war' }, null, (err, body) => { +libros.nsert({ name: 'The Art of war' }, null, (err, body) => { if (err) { - console. og(err); + console.og(err); } else { - consola. og(body); + consola.og(body); } }); // Obtén una lista de todos los libros -libros. ist((err, body) => { +libros.ist((err, body) => { if (err) { - consola. og(err); + consola.og(err); } else { console.log(body.rows); } @@ -139,11 +139,11 @@ $ npm instalar nivel de nivelación const levelup = require('levelup'); const db = levelup('./mydb'); -db. ut('nombre', 'LevelUP', (err) => { +db.ut('nombre', 'LevelUP', (err) => { if (err) return console.log('¡Ooops!', err); - db. et('nombre', (err, value) => { - if (err) return consola. og('¡Ooops!', err); + db.et('nombre', (err, value) => { + if (err) return consola.og('¡Ooops!', err); console.log(`name=${value}`); }); @@ -192,7 +192,7 @@ connection.end(); $ npm install mongodb ``` -### Ejemplo (v2.*) +### Ejemplo (v2.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -200,17 +200,17 @@ const MongoClient = require('mongodb').MongoClient; MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { if (err) throw err; - db. ollection('mammals') + db.ollection('mammals') .find() - . oArray((err, result) => { + .oArray((err, result) => { if (err) throw err; - consola. og(resultado); + consola.og(resultado); }); }); ``` -### Ejemplo (v3.*) +### Ejemplo (v3.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -218,14 +218,14 @@ const MongoClient = require('mongodb').MongoClient; MongoClient.connect('mongodb://localhost:27017/animals', (err, client) => { if (err) throw err; - const db = client. b('animales'); + const db = client.b('animales'); db.collection('mammals') .find() - . oArray((err, result) => { + .oArray((err, result) => { if (err) throw err; - consola. og(resultado); + consola.og(resultado); }); }); ``` @@ -246,18 +246,18 @@ $ npm install neo4j-driver ```js const neo4j = require('neo4j-driver'); -const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth. asic('neo4j', 'letmein')); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth.asic('neo4j', 'letmein')); const session = driver.session(); session.readTransaction((tx) => { return tx - . un('MATCH (n) RETURN count(n) AS count') + .un('MATCH (n) RETURN count(n) AS count') .then((res) => { - console.log(res.records[0]. et('count')); + console.log(res.records[0].et('count')); }) .catch((error) => { - consola. og(error); + consola.og(error); }); }); ``` @@ -323,12 +323,12 @@ const pgp = require('pg-promise')(/* options */); const db = pgp('postgres://username:password@host:port/database'); db.one('SELECT $1 AS value', 123) - . hen((data) => { + .hen((data) => { console.log('DATA:', data.value); }) - . atch((error) => { + .atch((error) => { console.log('ERROR:', error); -}); + }); ``` ## Redis @@ -351,15 +351,14 @@ client.on('error', (err) => { console.log(`Error ${err}`); }); -cliente. et('clave de cadena', 'valor de cadena', redis.print); +cliente.et('clave de cadena', 'valor de cadena', redis.print); client.hset('clave hash', 'hashtest 1', 'some value', redis.print); -cliente. set(['hash key', 'hashtest 2', 'algún otro valor'], redis.print); Cliente - -. keys('clave hash', (err, respuestas) => { +cliente.set(['hash key', 'hashtest 2', 'algún otro valor'], redis.print); +Cliente.keys('clave hash', (err, respuestas) => { console.log(`${replies.length} respuestas:`); - respuestas. orEach((reply, i) => { - consola. og(` ${i}: ${reply}`); + respuestas.orEach((reply, i) => { + consola.og(` ${i}: ${reply}`); }); client.quit(); @@ -380,7 +379,7 @@ $ npm install tedious ```js const Connection = require('tedious').Connection; -const Request = require('tedious'). equest; +const Request = require('tedious').equest; const config = { server: 'localhost', @@ -395,9 +394,9 @@ const config = { const connection = new Connection(config); -connection. n('connect', (err) => { +connection.n('connect', (err) => { if (err) { - consola. og(err); + consola.og(err); } else { executeStatement(); } @@ -406,19 +405,19 @@ connection. n('connect', (err) => { function executeStatement() { request = new Request("select 123, 'hola mundo'", (err, rowCount) => { if (err) { - consola. og(err); + consola.og(err); } else { - consola. og(`${rowCount} filas`); + consola.og(`${rowCount} filas`); } - conexión. lose(); + conexión.lose(); }); request.on('fila', (columnas) => { - columnas. orEach((column) => { + columnas.orEach((column) => { if (column.value === null) { - consola. og('NULL'); + consola.og('NULL'); } else { - console.log(column. alue); + console.log(column.alue); } }); }); @@ -444,17 +443,17 @@ const sqlite3 = require('sqlite3').verbose(); const db = new sqlite3.Database(':memory:'); db.serialize(() => { - db. un('CREATE TABLE lorem (info TEXT)'); - const stmt = db. repare('INSERT INTO Lorem VALUES (?)'); + db.un('CREATE TABLE lorem (info TEXT)'); + const stmt = db.repare('INSERT INTO Lorem VALUES (?)'); for (let i = 0; i < 10; i++) { - stmt. un(`Ipsum ${i}`); + stmt.un(`Ipsum ${i}`); } stmt.finalize(); - db. ach('SELECT rowid AS id, info FROM lorem', (err, row) => { - consola. og(`${row.id}: ${row.info}`); + db.ach('SELECT rowid AS id, info FROM lorem', (err, row) => { + consola.og(`${row.id}: ${row.info}`); }); }); @@ -480,7 +479,7 @@ const client = elasticsearch.Client({ }); client - . earch({ + .earch({ index: 'libros', tipo: 'libro', body: { @@ -492,12 +491,12 @@ client }, }, }) - . hen( + .hen( (response) => { - const hits = response.hits. its; + const hits = response.hits.its; }, (error) => { - consola. race(error.message); + consola.race(error.message); } -); + ); ``` diff --git a/src/content/pages/es/guide/migrating-4.mdx b/src/content/pages/es/guide/migrating-4.mdx index 445b2e8bf2..2aacb9445c 100644 --- a/src/content/pages/es/guide/migrating-4.mdx +++ b/src/content/pages/es/guide/migrating-4.mdx @@ -5,7 +5,7 @@ description: Una guía para migrar sus aplicaciones Express.js de la versión 3 import Alert from '@components/primitives/Alert/Alert.astro'; -Express 4 es un cambio de ruptura de Express 3. Esto significa que una aplicación Express 3 funcionará *no* si actualiza la versión Express en sus dependencias. +Express 4 es un cambio de ruptura de Express 3. Esto significa que una aplicación Express 3 funcionará _no_ si actualiza la versión Express en sus dependencias. Este artículo cubre: @@ -27,8 +27,8 @@ Hay varios cambios significativos en Express 4:
      • - Cambios a Express core y middleware. Las dependencias de - Conectar y middleware integrados fueron eliminadas, por lo que debe añadir middleware usted mismo. + Cambios a Express core y middleware. Las dependencias de Conectar y + middleware integrados fueron eliminadas, por lo que debe añadir middleware usted mismo.
      • Cambia al sistema de enrutamiento. @@ -40,8 +40,8 @@ Hay varios cambios significativos en Express 4: Ver también: -* [Nuevas características en 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) -* [Migración de 3.x a 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) +- [Nuevas características en 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +- [Migración de 3.x a 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) ### Cambios al sistema Express core y middleware @@ -214,8 +214,8 @@ el middleware `router`. La forma en que defines las rutas no ha cambiado, pero el sistema de enrutamiento tiene dos características nuevas para ayudar a organizar tus rutas: -* Un nuevo método, `app.route()`, para crear manejadores de rutas encadenables para una ruta de ruta. -* Una nueva clase, `express.Router`, para crear manejadores modulares de rutas montables. +- Un nuevo método, `app.route()`, para crear manejadores de rutas encadenables para una ruta de ruta. +- Una nueva clase, `express.Router`, para crear manejadores modulares de rutas montables. #### método `app.route()` @@ -229,14 +229,14 @@ Aquí hay un ejemplo de manejadores encadenados de rutas que se definen usando l app .route('/book') .get((req, res) => { - res. end('Obtén un libro al azar'); + res.end('Obtén un libro al azar'); }) - . ost((req, res) => { + .ost((req, res) => { res.send('Agregar un libro'); }) - . ut((req, res) => { + .ut((req, res) => { res.send('Actualizar el libro'); -}); + }); ``` #### Clase `express.Router` @@ -298,7 +298,9 @@ La siguiente tabla muestra otros cambios pequeños pero importantes en Express 4 Node.js - Express 4 requiere Node.js 0.10.x o posterior y ha eliminado el soporte para Node.js 0.8.x. + + Express 4 requiere Node.js 0.10.x o posterior y ha eliminado el soporte para Node.js 0.8.x. + `http.createServer()` @@ -358,8 +360,8 @@ La siguiente tabla muestra otros cambios pequeños pero importantes en Express 4 `res.setHeader('Set-Cookie', val)` - La funcionalidad ahora se limita a establecer el valor básico de la cookie. Usa `res.cookie()` para añadir funcionalidad - . + La funcionalidad ahora se limita a establecer el valor básico de la cookie. Usa `res.cookie()` + para añadir funcionalidad . @@ -385,26 +387,26 @@ var path = require('path'); var app = express(); // todos los entornos -app. et('puerto', process.env.PORT || 3000); +app.et('puerto', process.env.PORT || 3000); app.set('views', path.join(__dirname, 'views')); app.set('view engine', 'pug'); app.use(express.favicon()); app.use(express.logger('dev')); app.use(express.methodOverride()); -app.use(express. ession({ secret: 'your secret here' })); +app.use(express.ession({ secret: 'your secret here' })); app.use(express.bodyParser()); app.use(app.router); -app.use(express. tatic(path.join(__dirname, 'public'))); +app.use(express.tatic(path.join(__dirname, 'public'))); // desarrolla sólo if (app.get('env') === 'development') { - app. se(express.errorHandler()); + app.se(express.errorHandler()); } app.get('/', routes.index); app.get('/users', user.list); -http. reateServer(app).listen(app.get('port'), () => { +http.reateServer(app).listen(app.get('port'), () => { console.log('Express server listening on port ' + app.get('port')); }); ``` @@ -505,34 +507,34 @@ var errorHandler = require('errorhandler'); var app = express(); // todos los entornos -app. et('puerto', process.env.PORT || 3000); +app.et('puerto', process.env.PORT || 3000); app.set('views', path.join(__dirname, 'views')); app.set('view engine', 'pug'); app.use(favicon(path.join(__dirname, '/public/favicon.ico'))); app.use(logger('dev')); -app. se(methodOverride()); -app. se( +app.se(methodOverride()); +app.se( session({ resave: true, saveUninitialized: true, secretos: 'uwotm8', }) ); -aplicaciones. se(bodyParser.json()); +aplicaciones.se(bodyParser.json()); app.use(bodyParser.urlencoded({ extended: true })); app.use(multer()); app.use(express.static(path.join(__dirname, 'public'))); -app.get('/', rutas. ndex); +app.get('/', rutas.ndex); app.get('/users', user.list); // middleware de manejo de error debe ser cargado después de la carga de las rutas -if (app. et('env') === 'development') { - app. se(errorHandler()); +if (app.et('env') === 'development') { + app.se(errorHandler()); } var server = http.createServer(app); -server.listen(app. et('puerto'), () => { +server.listen(app.et('puerto'), () => { console.log('Servidor expreso escuchando en el puerto ' + app.get('port')); }); ``` @@ -595,9 +597,9 @@ Express 4. Las opciones de comando y uso siguen siendo en gran medida las mismas, con las siguientes excepciones: -* Se ha eliminado la opción `--sessions`. -* Se ha eliminado la opción `--jshtml`. -* Se añadió la opción `--hogan` para soportar [Hogan.js](http://twitter.github.io/hogan.js/). +- Se ha eliminado la opción `--sessions`. +- Se ha eliminado la opción `--jshtml`. +- Se añadió la opción `--hogan` para soportar [Hogan.js](http://twitter.github.io/hogan.js/). ### Ejemplo diff --git a/src/content/pages/es/guide/migrating-5.mdx b/src/content/pages/es/guide/migrating-5.mdx index 92e0ff5498..8a7f831a4a 100644 --- a/src/content/pages/es/guide/migrating-5.mdx +++ b/src/content/pages/es/guide/migrating-5.mdx @@ -166,7 +166,7 @@ app.del('/user/:id', (req, res) => { }); // v5 -app. elete('/user/:id', (req, res) => { +app.elete('/user/:id', (req, res) => { res.send(`DELETE /user/${req.params.id}`); }); ``` @@ -198,14 +198,14 @@ npx codemod@latest @expressjs/pluralize-nombre-método- // v4 app.all('/', (req, res) => { req.acceptsCharset('utf-8'); - req. cceptsEncoding('br'); + req.cceptsEncoding('br'); req.acceptsLanguage('en'); // ... }); // v5 -app. ll('/', (req, res) => { +app.ll('/', (req, res) => { req.acceptsCharsets('utf-8'); req.acceptsEncodings('br'); req.acceptsLanguages('es'); @@ -237,7 +237,7 @@ codemod@latest @expressjs/explícit-request-params npx // v4 app.post('/user', (req, res) => { const id = req.param('id'); - const body = req. aram('body'); + const body = req.aram('body'); const query = req.param('query'); // ... @@ -245,7 +245,7 @@ app.post('/user', (req, res) => { // v5 app.post('/user', (req, res) => { - const id = req.params. d; + const id = req.params.d; const body = req.body; const query = req.query; @@ -273,7 +273,7 @@ app.post('/user', (req, res) => { }); // v5 -app. ost('/user', (req, res) => { +app.ost('/user', (req, res) => { res.status(201).json({ name: 'Ruben' }); }); ``` @@ -298,7 +298,7 @@ app.post('/user', (req, res) => { }); // v5 -app. ost('/user', (req, res) => { +app.ost('/user', (req, res) => { res.status(201).jsonp({ name: 'Ruben' }); }); ``` @@ -323,7 +323,7 @@ app.get('/user', (req, res) => { }); // v5 -app. et('/user', (req, res) => { +app.et('/user', (req, res) => { res.redirect(301, '/users'); }); ``` @@ -348,7 +348,7 @@ app.get('/user', (req, res) => { }); // v5 -app. et('/user', (req, res) => { +app.et('/user', (req, res) => { res.redirect(req.get('Referrer') || '/'); }); ``` @@ -373,7 +373,7 @@ app.get('/user', (req, res) => { }); // v5 -app. et('/user', (req, res) => { +app.et('/user', (req, res) => { res.status(200).send({ name: 'Ruben' }); }); ``` @@ -410,12 +410,12 @@ La función `res.sendfile()` ha sido reemplazada por una versión `res.sendFile( **Nota:** En Express 5, `res. endFile()` utiliza el paquete `mime-types` para la detección de tipos MIME, que devuelve diferentes valores de Tipo de Contenido que Express 4 para varios tipos de archivo comunes: -* Archivos JavaScript (.js): ahora "text/javascript" en lugar de "application/javascript" -* Archivos JSON (.json): ahora "application/json" en lugar de "text/json" -* Archivos CSS (.css): ahora "text/css" en lugar de "text/plain" -* Archivos XML (.xml): ahora "application/xml" en lugar de "text/xml" -* Archivos de fuente (.woff): ahora "font/woff" en lugar de "application/font-woff" -* Archivos SVG (.svg): ahora "image/svg+xml" en lugar de "application/svg+xml" +- Archivos JavaScript (.js): ahora "text/javascript" en lugar de "application/javascript" +- Archivos JSON (.json): ahora "application/json" en lugar de "text/json" +- Archivos CSS (.css): ahora "text/css" en lugar de "text/plain" +- Archivos XML (.xml): ahora "application/xml" en lugar de "text/xml" +- Archivos de fuente (.woff): ahora "font/woff" en lugar de "application/font-woff" +- Archivos SVG (.svg): ahora "image/svg+xml" en lugar de "application/svg+xml" Puedes reemplazar las firmas obsoletas con el siguiente comando: @@ -449,12 +449,12 @@ Usa el [`mime-types` paquete](https://github.com/jshttp/mime-types) para trabaja **Importante:** Este cambio afecta no sólo al uso directo de `express.static.mime` sino también a otros métodos Express que dependen de la detección de tipo MIME, como `res.sendFile()`. Los siguientes tipos MIME han cambiado de Express 4: -* Archivos JavaScript (.js): ahora servido como "text/javascript" en lugar de "application/javascript" -* Archivos JSON (.json): ahora servido como "application/json" en lugar de "text/json" -* Archivos CSS (.css): ahora servido como "text/css" en lugar de "text/plain" -* Archivos HTML (): ahora servido como "text/html; charset=utf-8" en lugar de sólo "text/html" -* Archivos XML (.xml): ahora servido como "application/xml" en lugar de "text/xml" -* Archivos de fuente (.woff): ahora servido como "font/woff" en lugar de "application/font-woff" +- Archivos JavaScript (.js): ahora servido como "text/javascript" en lugar de "application/javascript" +- Archivos JSON (.json): ahora servido como "application/json" en lugar de "text/json" +- Archivos CSS (.css): ahora servido como "text/css" en lugar de "text/plain" +- Archivos HTML (): ahora servido como "text/html; charset=utf-8" en lugar de sólo "text/html" +- Archivos XML (.xml): ahora servido como "application/xml" en lugar de "text/xml" +- Archivos de fuente (.woff): ahora servido como "font/woff" en lugar de "application/font-woff" ```js // v4 @@ -490,7 +490,7 @@ DEBUG=expresar:*,router,router:* node index.js Ruta de ruta que coincide con la sintaxis es cuando se proporciona una cadena como el primer parámetro a las APIs `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, y `router.use()`. Se han realizado los siguientes cambios en cómo la cadena de ruta se corresponde con una solicitud entrante: -* El comodín `*` debe tener un nombre, coincidiendo con el comportamiento de los parámetros `:`, use `/*splat` en lugar de `/*` +- El comodín `*` debe tener un nombre, coincidiendo con el comportamiento de los parámetros `:`, use `/*splat` en lugar de `/*` ```js // v4 @@ -499,7 +499,7 @@ app.get('/*', async (req, res) => { }); // v5 -app. et('/*splat', async (req, res) => { +app.et('/*splat', async (req, res) => { res.send('ok'); }); ``` @@ -516,7 +516,7 @@ app.get('/{*splat}', async (req, res) => { -* El carácter opcional `?` ya no es compatible, utilice llaves en su lugar. +- El carácter opcional `?` ya no es compatible, utilice llaves en su lugar. ```js // v4 @@ -525,12 +525,12 @@ app.get('/:file.:ext?', async (req, res) => { }); // v5 -app. et('/:file{.:ext}', async (req, res) => { +app.et('/:file{.:ext}', async (req, res) => { res.send('ok'); }); ``` -* Los caracteres de expresión regular no son compatibles. Por ejemplo: +- Los caracteres de expresión regular no son compatibles. Por ejemplo: ```js app.get('/[discussion|page]/:slug', async (req, res) => { @@ -546,8 +546,8 @@ app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { }); ``` -* Algunos caracteres han sido reservados para evitar confusión durante la actualización (`()[]?+!`), use `\` para escapar de ellos. -* Los nombres de parámetros ahora soportan identificadores JavaScript válidos, o citan como `:"this"`. +- Algunos caracteres han sido reservados para evitar confusión durante la actualización (`()[]?+!`), use `\` para escapar de ellos. +- Los nombres de parámetros ahora soportan identificadores JavaScript válidos, o citan como `:"this"`. ### Las promesas rechazadas manejadas por middleware y manejadores @@ -619,7 +619,7 @@ Los comodines (por ejemplo, `/*splat`) capturan segmentos de ruta como una matri ```js app.get('/*splat', (req, res) => { // GET /foo/bar - console.dir(req. arams); + console.dir(req.arams); // => [Object: null prototype] { splat: [ 'foo', 'bar' ] } }); ``` @@ -632,21 +632,21 @@ En Express 4, los comodines no coinciden eran cadenas vacías (`''`) y los pará // v4: unmatched wildcard is empty string app.get('/*', (req, res) => { // GET / - console.dir(req. arams); + console.dir(req.arams); // => { '0': '' } }); // v4: unmatched optional param is undefined -app. et('/:file.:ext?', (req, res) => { +app.et('/:file.:ext?', (req, res) => { // GET /image - console. ir(req.params); + console.ir(req.params); // => { file: 'image', ext: undefined } }); // v5: unmatched optional param is omitted app.get('/:file{. ext}', (req, res) => { // GET /image - console.dir(req. arams); + console.dir(req.arams); // => [Object: null prototype] { file: 'image' } }); ``` diff --git a/src/content/pages/es/resources/glossary.mdx b/src/content/pages/es/resources/glossary.mdx index 18acaa588f..59f1021c1b 100644 --- a/src/content/pages/es/resources/glossary.mdx +++ b/src/content/pages/es/resources/glossary.mdx @@ -25,9 +25,9 @@ Una biblioteca de soporte multiplataforma que se centra en E/S asíncrona, desar Una función que es invocada por la capa de enrutamiento Express antes del gestor de solicitud final, y por lo tanto se encuentra en el medio entre una solicitud cruda y la ruta final deseada. Unos pocos puntos finos de terminología en torno a middleware: -* `var foo = require('middleware')` es llamado *requiring* o *using* un módulo Node.js. Luego la instrucción `var mw = foo()` típicamente devuelve el middleware. -* `app.use(mw)` se llama *agregando el middleware a la pila global de procesamiento de datos*. -* `app.get('/foo', mw, function (req, res) { ... })` se llama *adding the middleware to the "GET /foo" processing stack*. +- `var foo = require('middleware')` es llamado _requiring_ o _using_ un módulo Node.js. Luego la instrucción `var mw = foo()` típicamente devuelve el middleware. +- `app.use(mw)` se llama _agregando el middleware a la pila global de procesamiento de datos_. +- `app.get('/foo', mw, function (req, res) { ... })` se llama _adding the middleware to the "GET /foo" processing stack_. ### Node.js diff --git a/src/content/pages/es/resources/utils.md b/src/content/pages/es/resources/utils.md index a644860fee..c3fb043917 100644 --- a/src/content/pages/es/resources/utils.md +++ b/src/content/pages/es/resources/utils.md @@ -8,15 +8,15 @@ description: Descubra los módulos de utilidad relacionados con Express.js y Nod La organización [pillarjs](https://github.com/pillarjs) de GitHub contiene varios módulos para funciones de utilidad que pueden ser generalmente útiles. -| Módulos de utilidad | Descripción | -| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Módulos de utilidad | Descripción | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [cookies](https://www.npmjs.com/package/cookies) | Obtener y configurar cookies HTTP(S) que se pueden firmar para evitar manipulaciones, usando Keygrip. Se puede usar con la librería HTTP de Node.js o como middleware Express. | -| [csrf](https://www.npmjs.com/package/csrf) | Contiene la lógica detrás de la creación y verificación de token CSRF. Utilice este módulo para crear un middleware CSRF personalizado. | -| [finalhandler](https://www.npmjs.com/package/finalhandler) | Función para invocar como paso final para responder a la petición HTTP. | -| [parseurl](https://www.npmjs.com/package/parseurl) | Analizar una URL con caché. | -| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Convierte una cadena de ruta tipo Express-style como \`\`/user/:name\` en una expresión regular. | -| [resolve-path](https://www.npmjs.com/package/resolve-path) | Resuelve una ruta relativa contra una ruta raíz con validación. | -| [router](https://www.npmjs.com/package/router) | Enrutador simple de tipo middleware. | -| [send](https://www.npmjs.com/package/send) | Biblioteca para streaming de archivos como respuesta HTTP, con soporte para respuestas parciales (rangos), negociación condicional-GET y eventos granulares. | +| [csrf](https://www.npmjs.com/package/csrf) | Contiene la lógica detrás de la creación y verificación de token CSRF. Utilice este módulo para crear un middleware CSRF personalizado. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Función para invocar como paso final para responder a la petición HTTP. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Analizar una URL con caché. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Convierte una cadena de ruta tipo Express-style como \`\`/user/:name\` en una expresión regular. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Resuelve una ruta relativa contra una ruta raíz con validación. | +| [router](https://www.npmjs.com/package/router) | Enrutador simple de tipo middleware. | +| [send](https://www.npmjs.com/package/send) | Biblioteca para streaming de archivos como respuesta HTTP, con soporte para respuestas parciales (rangos), negociación condicional-GET y eventos granulares. | Para módulos adicionales relacionados con HTTP, consulte [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/es/support.md b/src/content/pages/es/support.md index d70f83842d..22d7eef706 100644 --- a/src/content/pages/es/support.md +++ b/src/content/pages/es/support.md @@ -7,14 +7,14 @@ Sólo se admite la última versión de cualquier línea de lanzamiento mayor. Las versiones que son EOL (end-of-life) _pueden_ recibir actualizaciones para vulnerabilidades de seguridad críticas, pero el equipo de Express no ofrece ninguna garantía y no planea abordar o corregir versiones para ningún problema encontrado. -| Versión principal | Versión mínima de Node.js | Inicio de Soporte | Fecha de fin de soporte | -| ------------------------------------------- | ----------------------------------------- | ------------------ | ----------------------- | -| [**v5.x**](/en/5x/api) | 18 | Septiembre de 2024 | **en curso** | -| [**v4.x**](/en/4x/api) | 0.10.0 | Abril de 2014 | **en curso** | -| [**v3.x**](/en/3x/api) | 0.8.0 | Octubre de 2012 | Julio de 2015 | -| [**v2.x**](/2x/) | 0.4.1 | Marzo de 2011 | Julio de 2012 | -| **v1.x** | 0.2.0 | Diciembre 2010 | Marzo de 2011 | -| **v0.14.x** | 0.1.98 | Diciembre 2010 | Diciembre 2010 | +| Versión principal | Versión mínima de Node.js | Inicio de Soporte | Fecha de fin de soporte | +| ---------------------- | ------------------------- | ------------------ | ----------------------- | +| [**v5.x**](/en/5x/api) | 18 | Septiembre de 2024 | **en curso** | +| [**v4.x**](/en/4x/api) | 0.10.0 | Abril de 2014 | **en curso** | +| [**v3.x**](/en/3x/api) | 0.8.0 | Octubre de 2012 | Julio de 2015 | +| [**v2.x**](/2x/) | 0.4.1 | Marzo de 2011 | Julio de 2012 | +| **v1.x** | 0.2.0 | Diciembre 2010 | Marzo de 2011 | +| **v0.14.x** | 0.1.98 | Diciembre 2010 | Diciembre 2010 | ## Opciones de soporte comercial diff --git a/src/content/pages/fr/advanced/best-practice-performance.md b/src/content/pages/fr/advanced/best-practice-performance.md index 65b26fdabe..70525e8e1f 100644 --- a/src/content/pages/fr/advanced/best-practice-performance.md +++ b/src/content/pages/fr/advanced/best-practice-performance.md @@ -208,7 +208,7 @@ Il y a deux façons d'utiliser les systèmes d'initialisation avec votre applica Systemd est un gestionnaire de systèmes et de services Linux. La plupart des grandes distributions Linux ont adopté le système comme système d'initialisation par défaut. -Un fichier de configuration du service système est appelé un fichier _unit avec un nom de fichier se terminant par `.service`. Voici un exemple de fichier d'unité pour gérer une application Node directement. Remplacez les valeurs placées en `` pour votre système et votre application: +Un fichier de configuration du service système est appelé un fichier \_unit avec un nom de fichier se terminant par `.service`. Voici un exemple de fichier d'unité pour gérer une application Node directement. Remplacez les valeurs placées en `` pour votre système et votre application: ```sh [Unit] diff --git a/src/content/pages/fr/advanced/best-practice-security.mdx b/src/content/pages/fr/advanced/best-practice-security.mdx index 91ef91137b..2638d8e2d4 100644 --- a/src/content/pages/fr/advanced/best-practice-security.mdx +++ b/src/content/pages/fr/advanced/best-practice-security.mdx @@ -1,11 +1,11 @@ --- -title: "Meilleures pratiques de production : Sécurité" +title: 'Meilleures pratiques de production : Sécurité' description: Découvrez les meilleures pratiques de sécurité cruciales pour les applications Express en production, y compris l'utilisation de TLS, la validation des entrées, les cookies sécurisés et la prévention des vulnérabilités. --- import Alert from '@components/primitives/Alert/Alert.astro'; -Le terme *"production"* désigne l'étape du cycle de vie du logiciel quand une application ou une API est généralement disponible pour ses utilisateurs finaux ou ses consommateurs. Par contre, dans l'étape *"développement"*, vous êtes toujours en train d'écrire et de tester du code, et l'application n'est pas ouverte à un accès externe. Les environnements système correspondants sont respectivement les environnements *production* et *development*. +Le terme _"production"_ désigne l'étape du cycle de vie du logiciel quand une application ou une API est généralement disponible pour ses utilisateurs finaux ou ses consommateurs. Par contre, dans l'étape _"développement"_, vous êtes toujours en train d'écrire et de tester du code, et l'application n'est pas ouverte à un accès externe. Les environnements système correspondants sont respectivement les environnements _production_ et _development_. Les environnements de développement et de production sont généralement mis en place différemment et ont des exigences très différentes. Ce qui est bon dans le développement peut ne pas être acceptable dans la production. Par exemple, dans un environnement de développement, vous pouvez vouloir une journalisation détaillée des erreurs pour le débogage, alors que le même comportement peut devenir une préoccupation de sécurité dans un environnement de production. Et en matière de développement, vous n'avez pas à vous soucier de l'évolutivité, de la fiabilité et de la performance, alors que ces préoccupations deviennent cruciales dans la production. @@ -18,21 +18,21 @@ de sécurité [/en/resources/contributing#security-policies-and-procedures). Les meilleures pratiques de sécurité pour les applications Express en production comprennent: -* [Meilleures pratiques de production : Sécurité](#production-best-practices-security) - * [Overview](#overview) - * [Ne pas utiliser de versions obsolètes ou vulnérables d'Express] (#dont-use-deprecated-or-vulnerable-versions-of-express) - * [Utiliser TLS](#use-tls) - * [Ne pas faire confiance à la saisie de l'utilisateur](#do-not-trust-user-input) - * [Empêcher les redirections ouvertes](#prevent-open-redirects) - * [Utiliser le casque](#use-helmet) - * [Réduire l'empreinte digitale](#reduce-fingerprinting) - * (#use-cookies-securely) - * [Ne pas utiliser le nom du cookie de session par défaut](#dont-use-the-default-session-cookie-name) - * (#set-cookie-security-options) - * [Empêcher les attaques par force brute contre l'autorisation] (#prevent-brute-force-attacks-against-authorization) - * [Assurez-vous que vos dépendances sont sécurisées](#ensure-your-dependencies-are-secure) - * [Éviter les autres vulnérabilités connues] (#avoid-other-known-vulnerabilities) - * [Considérations supplémentaires](#additional-considerations) +- [Meilleures pratiques de production : Sécurité](#production-best-practices-security) + - [Overview](#overview) + - [Ne pas utiliser de versions obsolètes ou vulnérables d'Express] (#dont-use-deprecated-or-vulnerable-versions-of-express) + - [Utiliser TLS](#use-tls) + - [Ne pas faire confiance à la saisie de l'utilisateur](#do-not-trust-user-input) + - [Empêcher les redirections ouvertes](#prevent-open-redirects) + - [Utiliser le casque](#use-helmet) + - [Réduire l'empreinte digitale](#reduce-fingerprinting) + - (#use-cookies-securely) + - [Ne pas utiliser le nom du cookie de session par défaut](#dont-use-the-default-session-cookie-name) + - (#set-cookie-security-options) + - [Empêcher les attaques par force brute contre l'autorisation] (#prevent-brute-force-attacks-against-authorization) + - [Assurez-vous que vos dépendances sont sécurisées](#ensure-your-dependencies-are-secure) + - [Éviter les autres vulnérabilités connues] (#avoid-other-known-vulnerabilities) + - [Considérations supplémentaires](#additional-considerations) ## Ne pas utiliser les versions obsolètes ou vulnérables de Express @@ -44,7 +44,7 @@ Assurez-vous également que vous n'utilisez aucune des versions vulnérables Exp Si votre application traite ou transmet des données sensibles, utilisez [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) pour sécuriser la connexion et les données. Cette technologie crypte les données avant qu'elles ne soient envoyées du client au serveur, empêchant ainsi certains hacks courants (et faciles). Bien que les requêtes Ajax et POST puissent ne pas être visiblement évidentes et semblent "cachées" dans les navigateurs, leur trafic réseau est vulnérable à [sniffing de paquets] (https://en.wikipedia.org/wiki/Packet_analyzer) et aux [attaques de l'homme au milieu] (https://en.wikipedia.org/wiki/Man-in-the-middle_attack). -Il se peut que vous soyez familier avec le cryptage Secure Socket Layer (SSL) . [TLS est simplement la prochaine progression de SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). En d'autres termes, si vous utilisiez SSL auparavant, envisagez la mise à niveau vers TLS. En général, nous recommandons à Nginx de gérer les TLS. Pour une bonne référence pour configurer TLS sur Nginx (et d'autres serveurs), voir [Configurations de serveur recommandées (Mozilla Wiki)] (https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). +Il se peut que vous soyez familier avec le cryptage Secure Socket Layer (SSL) . [TLS est simplement la prochaine progression de SSL](). En d'autres termes, si vous utilisiez SSL auparavant, envisagez la mise à niveau vers TLS. En général, nous recommandons à Nginx de gérer les TLS. Pour une bonne référence pour configurer TLS sur Nginx (et d'autres serveurs), voir [Configurations de serveur recommandées (Mozilla Wiki)] (https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). De plus, un outil pratique pour obtenir un certificat TLS gratuit est [Let's Encrypt](https://letsencrypt.org/about/), un outil gratuit, automatisé, et l'autorité de certification ouverte (CA) fournie par le [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). @@ -55,7 +55,7 @@ En fin de compte, la responsabilité de valider et de gérer correctement les ty ### Empêcher les redirections ouvertes -Un exemple de saisie potentiellement dangereuse de l'utilisateur est une redirection _ouverte, où une application accepte une URL comme entrée utilisateur (souvent dans la requête URL, par exemple `? rl=https://exemple. ) et utilise `res.redirect`pour définir l'en-tête`location\` et +Un exemple de saisie potentiellement dangereuse de l'utilisateur est une redirection \_ouverte, où une application accepte une URL comme entrée utilisateur (souvent dans la requête URL, par exemple `? rl=https://exemple. ) et utilise `res.redirect`pour définir l'en-tête`location\` et retourne un statut 3xx. Une application doit valider qu'elle prend en charge la redirection vers l'URL entrante pour éviter d'envoyer des utilisateurs à des liens malveillants tels que des sites Web d'hameçonnage, entre autres risques. @@ -81,19 +81,19 @@ app.use((req, res) => { Helmet est une fonction middleware qui définit les en-têtes de réponse HTTP liés à la sécurité. Le casque définit par défaut les en-têtes suivants : -* `Content-Security-Policy` : Une puissante liste de ce qui peut se passer sur votre page qui atténue de nombreuses attaques -* `Cross-Origin-Opener-Policy`: Aide à isoler votre page -* `Cross-Origin-Resource-Policy`: empêche les autres de charger vos ressources cross-origin -* `Origin-Agent-Cluster`: Modifie l'isolement du processus pour qu'il soit basé sur l'origine -* `Referrer-Policy`: contrôle l'en-tête [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) -* `Strict-Transport-Security` : dit aux navigateurs de préférer HTTPS -* `X-Content-Type-Options`: évite [sniffing MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) -* `X-DNS-Prefetch-Control`: contrôle le préchargement DNS -* `X-Download-Options`: force les téléchargements à être sauvegardés (Internet Explorer uniquement) -* `X-Frame-Options`: En-tête hérité qui atténue les attaques [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) -* `X-Permitted-Cross-Domain-Policies`: Contrôle le comportement inter-domaine pour les produits Adobe, comme Acrobat -* `X-Powered-By`: Informations sur le serveur web. Supprimé parce qu'il peut être utilisé dans des attaques simples -* `X-XSS-Protection`: L'en-tête hérité qui tente d'atténuer [les attaques XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), mais rend les choses pires, alors le casque le désactive +- `Content-Security-Policy` : Une puissante liste de ce qui peut se passer sur votre page qui atténue de nombreuses attaques +- `Cross-Origin-Opener-Policy`: Aide à isoler votre page +- `Cross-Origin-Resource-Policy`: empêche les autres de charger vos ressources cross-origin +- `Origin-Agent-Cluster`: Modifie l'isolement du processus pour qu'il soit basé sur l'origine +- `Referrer-Policy`: contrôle l'en-tête [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) +- `Strict-Transport-Security` : dit aux navigateurs de préférer HTTPS +- `X-Content-Type-Options`: évite [sniffing MIME](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +- `X-DNS-Prefetch-Control`: contrôle le préchargement DNS +- `X-Download-Options`: force les téléchargements à être sauvegardés (Internet Explorer uniquement) +- `X-Frame-Options`: En-tête hérité qui atténue les attaques [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) +- `X-Permitted-Cross-Domain-Policies`: Contrôle le comportement inter-domaine pour les produits Adobe, comme Acrobat +- `X-Powered-By`: Informations sur le serveur web. Supprimé parce qu'il peut être utilisé dans des attaques simples +- `X-XSS-Protection`: L'en-tête hérité qui tente d'atténuer [les attaques XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), mais rend les choses pires, alors le casque le désactive Chaque en-tête peut être configuré ou désactivé. Pour en savoir plus à ce sujet, veuillez vous rendre sur [son site de documentation][helmet]. @@ -164,8 +164,8 @@ Pour vous assurer que les cookies n'ouvrent pas votre application aux exploitati Il y a deux principaux modules de session de cookies du middleware : -* [express-session](https://www.npmjs.com/package/express-session) qui remplace le middleware `express.session` intégré à Express 3.x. -* [cookie-session](https://www.npmjs.com/package/cookie-session) qui remplace le middleware `express.cookieSession` intégré à Express 3.x. +- [express-session](https://www.npmjs.com/package/express-session) qui remplace le middleware `express.session` intégré à Express 3.x. +- [cookie-session](https://www.npmjs.com/package/cookie-session) qui remplace le middleware `express.cookieSession` intégré à Express 3.x. La principale différence entre ces deux modules est la façon dont ils enregistrent les données de session des cookies. Le middleware [express-session](https://www.npmjs.com/package/express-session) stocke les données de session sur le serveur ; il n'enregistre que l'ID de session dans le cookie lui-même, pas les données de session. Par défaut, il utilise du stockage en mémoire et n'est pas conçu pour un environnement de production. En production, vous devrez configurer un magasin de session évolutif ; voir la liste des [magasins de sessions compatibles] (https://github.com/expressjs/session#compatible-session-stores). @@ -180,7 +180,7 @@ Pour éviter ce problème, utilisez des noms génériques de cookies; par exempl ```js const session = require('express-session'); app.set('trust proxy', 1); // trust first proxy -app. se( +app.se( session({ secret: 's3Cur3', name: 'sessionId', @@ -192,11 +192,11 @@ app. se( Définissez les options suivantes des cookies pour améliorer la sécurité : -* `secure` - Permet au navigateur d'envoyer le cookie uniquement via HTTPS. -* `httpOnly` - Assure que le cookie est envoyé uniquement sur HTTP(S), et non sur le JavaScript du client, aidant à se protéger contre les attaques de scripts intersites. -* `domain` - indique le domaine du cookie; utilisez-le pour comparer avec le domaine du serveur dans lequel l'URL est demandée. S'ils correspondent alors vérifiez l'attribut path suivant. -* `path` - indique le chemin du cookie; utilisez-le pour comparer le chemin de la requête. Si cela et le domaine correspondent, alors envoyez le cookie dans la requête. -* `expires` - utiliser pour définir la date d'expiration des cookies persistants. +- `secure` - Permet au navigateur d'envoyer le cookie uniquement via HTTPS. +- `httpOnly` - Assure que le cookie est envoyé uniquement sur HTTP(S), et non sur le JavaScript du client, aidant à se protéger contre les attaques de scripts intersites. +- `domain` - indique le domaine du cookie; utilisez-le pour comparer avec le domaine du serveur dans lequel l'URL est demandée. S'ils correspondent alors vérifiez l'attribut path suivant. +- `path` - indique le chemin du cookie; utilisez-le pour comparer le chemin de la requête. Si cela et le domaine correspondent, alors envoyez le cookie dans la requête. +- `expires` - utiliser pour définir la date d'expiration des cookies persistants. Voici un exemple utilisant [cookie-session](https://www.npmjs.com/package/cookie-session) middleware: @@ -267,10 +267,10 @@ Enfin, les applications Express—comme toutes les autres applications web&m Voici quelques autres recommandations de l'excellent [Liste de contrôle de sécurité Node.js](https://blog.risingstack.com/node-js-security-checklist/). Reportez-vous à cet article de blog pour tous les détails sur ces recommandations : -* Filtrer et nettoyer toujours les entrées de l'utilisateur pour se protéger contre les attaques de script intersite (XSS) et d'injection de commandes. -* Protégez contre les attaques d'injection SQL en utilisant des requêtes paramétrées ou des requêtes préparées. -* Utilisez l'outil [sqlmap](http://sqlmap.org/) pour détecter les vulnérabilités d'injection SQL dans votre application. -* Utilisez les outils [nmap](https://nmap.org/) et [sslyze](https://github.com/nabla-c0d3/sslyze) pour tester la configuration de vos codes SSL, , et renégociation ainsi que la validité de votre certificat. -* Utilisez [safe-regex](https://www.npmjs.com/package/safe-regex) pour vous assurer que vos expressions régulières ne sont pas susceptibles d'attaques [déni de service d'expression régulière](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS). +- Filtrer et nettoyer toujours les entrées de l'utilisateur pour se protéger contre les attaques de script intersite (XSS) et d'injection de commandes. +- Protégez contre les attaques d'injection SQL en utilisant des requêtes paramétrées ou des requêtes préparées. +- Utilisez l'outil [sqlmap](http://sqlmap.org/) pour détecter les vulnérabilités d'injection SQL dans votre application. +- Utilisez les outils [nmap](https://nmap.org/) et [sslyze](https://github.com/nabla-c0d3/sslyze) pour tester la configuration de vos codes SSL, , et renégociation ainsi que la validité de votre certificat. +- Utilisez [safe-regex](https://www.npmjs.com/package/safe-regex) pour vous assurer que vos expressions régulières ne sont pas susceptibles d'attaques [déni de service d'expression régulière](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS). [helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/fr/advanced/security-updates.mdx b/src/content/pages/fr/advanced/security-updates.mdx index d4439e7afb..5bca00be1e 100644 --- a/src/content/pages/fr/advanced/security-updates.mdx +++ b/src/content/pages/fr/advanced/security-updates.mdx @@ -24,42 +24,42 @@ de sécurité [/en/resources/contributing#security-policies-and-procedures). ## 4.x -* 4.21.2 - * La dépendance `path-to-regexp` a été mise à jour pour répondre à un [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). -* 4.21.1 - * Le `cookie` de dépendance a été mis à jour pour répondre à un [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), cela peut affecter votre application si vous utilisez `res.cookie`. -* 4.20.0 - * Correction de la vulnérabilité XSS dans `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). - * La dépendance `serve-static` a été mise à jour pour adresser un [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). - * La dépendance `send` a été mise à jour pour répondre à un [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). - * La dépendance `path-to-regexp` a été mise à jour pour répondre à un [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). - * La dépendance `body-parser` a été mise à jour pour administrer un [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), cela peut affecter votre application si vous aviez l'url en cours d'activation. -* 4.19.0, 4.19.1 - * Correction de la vulnérabilité de redirection ouverte dans `res.location` et `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). -* 4.17.3 - * La dépendance `qs` a été mise à jour pour répondre à un [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). Cela peut affecter votre application si les API suivantes sont utilisées: `req.query`, `req.body`, `req.param`. -* 4.16.0 - * La dépendance `transférée` a été mise à jour pour répondre à un [vulnerability](https://npmjs.com/advisories/527). Cela peut affecter votre application si les API suivantes sont utilisées: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. - * La dépendance `mime` a été mise à jour pour répondre à un [vulnerability](https://npmjs.com/advisories/535), mais ce problème n'a pas d'impact sur Express. - * La dépendance `send` a été mise à jour pour fournir une protection contre une vulnérabilité [Node.js 8.5.0](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). Ceci n'affecte que l'exécution Express sur la version spécifique de Node.js 8.5.0. -* 4.15.5 - * La dépendance `debug` a été mise à jour pour répondre à un [vulnerability](https://snyk.io/vuln/npm:debug:20170905), mais ce problème n'a pas d'impact sur Express. - * La dépendance `fresh` a été mise à jour pour répondre à un [vulnerability](https://npmjs.com/advisories/526). Cela affectera votre application si les API suivantes sont utilisées: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. -* 4.15.3 - * La dépendance `ms` a été mise à jour pour adresser un [vulnerability](https://snyk.io/vuln/npm:ms:20170412). Cela peut affecter votre application si des chaînes de caractères non fiables sont passées à l'option `maxAge` dans les APIs suivantes: `express.static`, `res.sendfile` et `res.sendFile`. -* 4.15.2 - * La dépendance `qs` a été mise à jour pour répondre à un [vulnerability](https://snyk.io/vuln/npm:qs:20170213), mais ce problème n'a pas d'impact sur Express. Mettre à jour la version 4.15.2 est une bonne pratique, mais pas nécessaire pour résoudre la vulnérabilité. -* 4.11.1 - * Correction de la vulnérabilité de divulgation de chemin racine dans `express.static`, `res.sendfile` et `res.sendFile` -* 4.10.7 - * Correction de la vulnérabilité de redirection ouverte dans `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 4.8.8 - * Correction de vulnérabilités de traversée de répertoire dans `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). -* 4.8.4 - * Node.js 0.10 peut fuir `fd`s dans certaines situations qui affectent `express.static` et `res.sendfile`. Des requêtes malveillantes pourraient provoquer une fuite de `fd`s et éventuellement entraîner des erreurs `EMFILE` et une incapacité du serveur. -* 4.8.0 - * Les tableaux d'analyse qui ont des index extrêmement élevés dans la chaîne de requête peuvent faire que le processus est à court de mémoire et planter le serveur. - * Les objets de chaîne de requête extrêmement imbriqués peuvent bloquer le processus et rendre le serveur temporairement inadapté. +- 4.21.2 + - La dépendance `path-to-regexp` a été mise à jour pour répondre à un [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +- 4.21.1 + - Le `cookie` de dépendance a été mis à jour pour répondre à un [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), cela peut affecter votre application si vous utilisez `res.cookie`. +- 4.20.0 + - Correction de la vulnérabilité XSS dans `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + - La dépendance `serve-static` a été mise à jour pour adresser un [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). + - La dépendance `send` a été mise à jour pour répondre à un [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + - La dépendance `path-to-regexp` a été mise à jour pour répondre à un [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + - La dépendance `body-parser` a été mise à jour pour administrer un [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), cela peut affecter votre application si vous aviez l'url en cours d'activation. +- 4.19.0, 4.19.1 + - Correction de la vulnérabilité de redirection ouverte dans `res.location` et `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +- 4.17.3 + - La dépendance `qs` a été mise à jour pour répondre à un [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). Cela peut affecter votre application si les API suivantes sont utilisées: `req.query`, `req.body`, `req.param`. +- 4.16.0 + - La dépendance `transférée` a été mise à jour pour répondre à un [vulnerability](https://npmjs.com/advisories/527). Cela peut affecter votre application si les API suivantes sont utilisées: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + - La dépendance `mime` a été mise à jour pour répondre à un [vulnerability](https://npmjs.com/advisories/535), mais ce problème n'a pas d'impact sur Express. + - La dépendance `send` a été mise à jour pour fournir une protection contre une vulnérabilité [Node.js 8.5.0](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). Ceci n'affecte que l'exécution Express sur la version spécifique de Node.js 8.5.0. +- 4.15.5 + - La dépendance `debug` a été mise à jour pour répondre à un [vulnerability](https://snyk.io/vuln/npm:debug:20170905), mais ce problème n'a pas d'impact sur Express. + - La dépendance `fresh` a été mise à jour pour répondre à un [vulnerability](https://npmjs.com/advisories/526). Cela affectera votre application si les API suivantes sont utilisées: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. +- 4.15.3 + - La dépendance `ms` a été mise à jour pour adresser un [vulnerability](https://snyk.io/vuln/npm:ms:20170412). Cela peut affecter votre application si des chaînes de caractères non fiables sont passées à l'option `maxAge` dans les APIs suivantes: `express.static`, `res.sendfile` et `res.sendFile`. +- 4.15.2 + - La dépendance `qs` a été mise à jour pour répondre à un [vulnerability](https://snyk.io/vuln/npm:qs:20170213), mais ce problème n'a pas d'impact sur Express. Mettre à jour la version 4.15.2 est une bonne pratique, mais pas nécessaire pour résoudre la vulnérabilité. +- 4.11.1 + - Correction de la vulnérabilité de divulgation de chemin racine dans `express.static`, `res.sendfile` et `res.sendFile` +- 4.10.7 + - Correction de la vulnérabilité de redirection ouverte dans `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 4.8.8 + - Correction de vulnérabilités de traversée de répertoire dans `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +- 4.8.4 + - Node.js 0.10 peut fuir `fd`s dans certaines situations qui affectent `express.static` et `res.sendfile`. Des requêtes malveillantes pourraient provoquer une fuite de `fd`s et éventuellement entraîner des erreurs `EMFILE` et une incapacité du serveur. +- 4.8.0 + - Les tableaux d'analyse qui ont des index extrêmement élevés dans la chaîne de requête peuvent faire que le processus est à court de mémoire et planter le serveur. + - Les objets de chaîne de requête extrêmement imbriqués peuvent bloquer le processus et rendre le serveur temporairement inadapté. ## 3.x @@ -72,16 +72,16 @@ Si vous ne pouvez pas mettre à jour après la version 3.x, veuillez considérer -* 3.19.1 - * Correction de la vulnérabilité de divulgation de chemin racine dans `express.static`, `res.sendfile` et `res.sendFile` -* 3.19.0 - * Correction de la vulnérabilité de redirection ouverte dans `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 3.16.10 - * Correction de vulnérabilités de traversée de répertoire dans `express.static`. -* 3.16.6 - * Node.js 0.10 peut fuir `fd`s dans certaines situations qui affectent `express.static` et `res.sendfile`. Des requêtes malveillantes pourraient provoquer une fuite de `fd`s et éventuellement entraîner des erreurs `EMFILE` et une incapacité du serveur. -* 3.16.0 - * Des tableaux d'analyse qui ont des index extrêmement élevés dans la chaîne de requête peuvent faire que le processus est à court de mémoire et planter le serveur. - * Les objets de chaîne de requête extrêmement imbriqués peuvent bloquer le processus et rendre le serveur temporairement inadapté. -* 3.3.0 - * La réponse 404 d'une tentative de substitution de méthode non supportée était susceptible d'attaques de type cross-site scripting. +- 3.19.1 + - Correction de la vulnérabilité de divulgation de chemin racine dans `express.static`, `res.sendfile` et `res.sendFile` +- 3.19.0 + - Correction de la vulnérabilité de redirection ouverte dans `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 3.16.10 + - Correction de vulnérabilités de traversée de répertoire dans `express.static`. +- 3.16.6 + - Node.js 0.10 peut fuir `fd`s dans certaines situations qui affectent `express.static` et `res.sendfile`. Des requêtes malveillantes pourraient provoquer une fuite de `fd`s et éventuellement entraîner des erreurs `EMFILE` et une incapacité du serveur. +- 3.16.0 + - Des tableaux d'analyse qui ont des index extrêmement élevés dans la chaîne de requête peuvent faire que le processus est à court de mémoire et planter le serveur. + - Les objets de chaîne de requête extrêmement imbriqués peuvent bloquer le processus et rendre le serveur temporairement inadapté. +- 3.3.0 + - La réponse 404 d'une tentative de substitution de méthode non supportée était susceptible d'attaques de type cross-site scripting. diff --git a/src/content/pages/fr/guide/database-integration.mdx b/src/content/pages/fr/guide/database-integration.mdx index 312c34f538..43778395ff 100644 --- a/src/content/pages/fr/guide/database-integration.mdx +++ b/src/content/pages/fr/guide/database-integration.mdx @@ -7,19 +7,19 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Ajouter la possibilité de connecter des bases de données à des applications Express est juste une question de charger un pilote Node.js approprié pour la base de données dans votre application. Ce document explique brièvement comment ajouter et utiliser certains des modules Node.js les plus populaires pour les systèmes de base de données dans votre application Express : -* [Cassandra](#cassandra) -* [Couchbase](#couchbase) -* [CouchDB](#couchdb) -* [LevelDB](#leveldb) -* [MySQL](#mysql) -* [MongoDB](#mongodb) -* [Neo4j](#neo4j) -* [Oracle](#oracle) -* [PostgreSQL](#postgresql) -* [Redis](#redis) -* [Serveur SQL](#sql-server) -* [SQLite](#sqlite) -* [Elasticsearch](#elasticsearch) +- [Cassandra](#cassandra) +- [Couchbase](#couchbase) +- [CouchDB](#couchdb) +- [LevelDB](#leveldb) +- [MySQL](#mysql) +- [MongoDB](#mongodb) +- [Neo4j](#neo4j) +- [Oracle](#oracle) +- [PostgreSQL](#postgresql) +- [Redis](#redis) +- [Serveur SQL](#sql-server) +- [SQLite](#sqlite) +- [Elasticsearch](#elasticsearch) @@ -44,7 +44,7 @@ $ npm install cassandra-driver const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['localhost'] }); -client. xecute('select key from system.local', (err, result) => { +client.xecute('select key from system.local', (err, result) => { if (err) throw err; console.log(result.rows[0]); }); @@ -139,11 +139,11 @@ $ npm install levelup levelup level down const levelup = require('levelup'); const db = levelup('./mydb'); -db. ut('name', 'LevelUP', (err) => { +db.ut('name', 'LevelUP', (err) => { if (err) return console.log('Ooops!', err); - db. et('name', (err, value) => { - if (err) return console. og('Ooops!', err); + db.et('name', (err, value) => { + if (err) return console.og('Ooops!', err); console.log(`name=${value}`); }); @@ -164,19 +164,19 @@ $ npm install mysql ```js const mysql = require('mysql'); -const connection = mysql. reateConnection({ +const connection = mysql.reateConnection({ hôte: 'localhost', user: 'dbuser', password: 's3kreee7', database: 'my_db', }); -connexion. onnect(); +connexion.onnect(); connection.query('SELECT 1 + 1 AS solution', (err, rows, fields) => { if (err) throw err; - console. og('La solution est : ', lignes[0].solution); + console.og('La solution est : ', lignes[0].solution); }); connection.end(); @@ -192,7 +192,7 @@ connection.end(); $ npm install mongodb ``` -### Exemple (v2.*) +### Exemple (v2.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -210,7 +210,7 @@ MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { }); ``` -### Exemple (v3.*) +### Exemple (v3.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -246,18 +246,18 @@ $ npm install neo4j-driver ```js const neo4j = require('neo4j-driver'); -const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth. asic('neo4j', 'letmein')); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth.asic('neo4j', 'letmein')); const session = driver.session(); session.readTransaction((tx) => { return tx - . un('MATCH (n) RETURN count(n) AS count') + .un('MATCH (n) RETURN count(n) AS count') .then((res) => { - console.log(res.records[0]. et('count')); + console.log(res.records[0].et('count')); }) .catch((error) => { - console. og(erreur); + console.og(erreur); }); }); ``` @@ -323,12 +323,12 @@ const pgp = require('pg-promise')(/* options */); const db = pgp('postgres://username:password@host:port/database'); db.one('SELECT $1 AS valeur', 123) - . hen((data) => { + .hen((data) => { console.log('DATA:', data.value); }) - . atch((error) => { + .atch((error) => { console.log('ERROR:', error); -}); + }); ``` ## Redis @@ -351,15 +351,14 @@ client.on('error', (err) => { console.log(`Error ${err}`); }); -client. et('string key', 'string val', redis.print); +client.et('string key', 'string val', redis.print); client.hset('hash key', 'hashtest 1', 'some value', redis.print); -client. set(['hash key', 'hashtest 2', 'une autre valeur'], redis.print); client - -. keys('clé de hachage', (err, replies) => { +client.set(['hash key', 'hashtest 2', 'une autre valeur'], redis.print); +client.keys('clé de hachage', (err, replies) => { console.log(`${replies.length} réponses:`); - réponses. orEach((reply, i) => { - console. og(` ${i}: ${reply}`); + réponses.orEach((reply, i) => { + console.og(` ${i}: ${reply}`); }); client.quit(); @@ -444,17 +443,17 @@ const sqlite3 = require('sqlite3').verbose(); const db = new sqlite3.Database(':memory:'); db.serialize(() => { - db. un('CREATE TABLE lorem (info TEXT)'); - const stmt = db. repare('INSERT INTO lorem VALUES (?)'); + db.un('CREATE TABLE lorem (info TEXT)'); + const stmt = db.repare('INSERT INTO lorem VALUES (?)'); for (let i = 0; i < 10; i++) { - stmt. un(`Ipsum ${i}`); + stmt.un(`Ipsum ${i}`); } stmt.finalize(); - db. ach('SELECT rowid AS id, info FROM lorem', (err, row) => { - console. og(`${row.id}: ${row.info}`); + db.ach('SELECT rowid AS id, info FROM lorem', (err, row) => { + console.og(`${row.id}: ${row.info}`); }); }); diff --git a/src/content/pages/fr/guide/migrating-4.mdx b/src/content/pages/fr/guide/migrating-4.mdx index 2de46d11f9..54320b08b6 100644 --- a/src/content/pages/fr/guide/migrating-4.mdx +++ b/src/content/pages/fr/guide/migrating-4.mdx @@ -5,7 +5,7 @@ description: Un guide pour migrer vos applications Express.js de la version 3 à import Alert from '@components/primitives/Alert/Alert.astro'; -Express 4 est un changement ininterrompu de Express 3. Cela signifie qu'une application Express 3 existante ne fonctionnera *pas* si vous mettez à jour la version Express dans ses dépendances. +Express 4 est un changement ininterrompu de Express 3. Cela signifie qu'une application Express 3 existante ne fonctionnera _pas_ si vous mettez à jour la version Express dans ses dépendances. Cet article couvre : @@ -27,8 +27,9 @@ Il y a plusieurs changements significatifs dans Express 4 :
        • - Changement de coeur et de système middleware Express. Les dépendances de - Connect et les middleware intégrés ont été supprimées, vous devez donc ajouter du middleware vous-même. + Changement de coeur et de système middleware Express. Les + dépendances de Connect et les middleware intégrés ont été supprimées, vous devez donc ajouter du + middleware vous-même.
        • Modifications au système de routage. @@ -40,8 +41,8 @@ Il y a plusieurs changements significatifs dans Express 4 : Voir aussi: -* [Nouvelles fonctionnalités en 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) -* [Migration de 3.x vers 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) +- [Nouvelles fonctionnalités en 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +- [Migration de 3.x vers 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) ### Changements vers le coeur Express et le système middleware @@ -214,8 +215,8 @@ le middleware `router`. The way you define routes is unchanged, but the routing system has two new features to help organize your routes: -* Une nouvelle méthode, `app.route()`, pour créer des gestionnaires de routes chaînables pour un chemin de route. -* Une nouvelle classe, `express.Router`, pour créer des gestionnaires de routes modulaires montables. +- Une nouvelle méthode, `app.route()`, pour créer des gestionnaires de routes chaînables pour un chemin de route. +- Une nouvelle classe, `express.Router`, pour créer des gestionnaires de routes modulaires montables. #### méthode `app.route()` @@ -231,12 +232,12 @@ app .get((req, res) => { end('Obtenir un livre aléatoire'); }) - . ost((req, res) => { + .ost((req, res) => { res.send('Ajouter un livre'); }) - . ut((req, res) => { + .ut((req, res) => { res.send('Mettre à jour le livre'); -}); + }); ``` #### Classe `express.Router` @@ -298,13 +299,17 @@ Le tableau suivant liste d'autres changements mineurs mais importants dans Expre Node.js - Express 4 nécessite Node.js 0.10.x ou ultérieur et a abandonné la prise en charge de Node.js 0.8.x. + + Express 4 nécessite Node.js 0.10.x ou ultérieur et a abandonné la prise en charge de Node.js + 0.8.x. + `http.createServer()` - Le module `http` n'est plus nécessaire, à moins que vous ayez besoin de travailler directement avec lui - (socket.io/SPDY/HTTPS). L'application peut être démarrée en utilisant la fonction `app.listen()`. + Le module `http` n'est plus nécessaire, à moins que vous ayez besoin de travailler directement + avec lui (socket.io/SPDY/HTTPS). L'application peut être démarrée en utilisant la fonction + `app.listen()`. @@ -358,8 +363,8 @@ Le tableau suivant liste d'autres changements mineurs mais importants dans Expre `res.setHeader('Set-Cookie', val)` - La fonctionnalité est maintenant limitée à définir la valeur de base des cookies. Utilisez `res.cookie()` pour ajouter une fonctionnalité - . + La fonctionnalité est maintenant limitée à définir la valeur de base des cookies. Utilisez + `res.cookie()` pour ajouter une fonctionnalité . @@ -385,26 +390,26 @@ var path = require('path'); var app = express(); // toutes les applications -environnement. et('port', process.env.PORT || 3000); +environnement.et('port', process.env.PORT || 3000); app.set('vues', path.join(__dirname, 'views')); app.set('voir engine', 'pug'); app.use(express.favicon()); app.use(express.logger('dev')); app.use(express.methodOverride()); -app.use(express. ession({ secret: 'votre secret ici' })); +app.use(express.ession({ secret: 'votre secret ici' })); app.use(express.bodyParser()); app.use(app.router); -app.use(express. tatic(path.join(__dirname, 'public'))); +app.use(express.tatic(path.join(__dirname, 'public'))); // développement seulement if (app.get('env') === 'development') { - app. se(express.errorHandler()); + app.se(express.errorHandler()); } app.get('/', routes.index); app.get('/users', user.list); -http. reateServer(app).listen(app.get('port'), () => { +http.reateServer(app).listen(app.get('port'), () => { console.log('Express server listening on port ' + app.get('port')); }); ``` @@ -595,9 +600,9 @@ Express 4. Les options de commande et l'utilisation restent en grande partie les mêmes, avec les exceptions suivantes : -* Suppression de l'option `--sessions`. -* Suppression de l'option `--jshtml`. -* Ajout de l'option `--hogan` pour supporter [Hogan.js](http://twitter.github.io/hogan.js/). +- Suppression de l'option `--sessions`. +- Suppression de l'option `--jshtml`. +- Ajout de l'option `--hogan` pour supporter [Hogan.js](http://twitter.github.io/hogan.js/). ### Exemple diff --git a/src/content/pages/fr/guide/migrating-5.mdx b/src/content/pages/fr/guide/migrating-5.mdx index 498ed9b852..457daf944c 100644 --- a/src/content/pages/fr/guide/migrating-5.mdx +++ b/src/content/pages/fr/guide/migrating-5.mdx @@ -166,7 +166,7 @@ app.del('/user/:id', (req, res) => { }); // v5 -application. elete('/user/:id', (req, res) => { +application.elete('/user/:id', (req, res) => { res.send(`DELETE /user/${req.params.id}`); }); ``` @@ -198,14 +198,14 @@ npx codemod@latest @expressjs/pluralize-method-names // v4 app.all('/', (req, res) => { req.acceptsCharset('utf-8'); - req. cceptsEncoding('br'); + req.cceptsEncoding('br'); req.acceptsLanguage('en'); // ... }); // v5 -application. ll('/', (req, res) => { +application.ll('/', (req, res) => { req.acceptsCharsets('utf-8'); req.acceptsEncodings('br'); req.acceptsLanguages('en'); @@ -237,7 +237,7 @@ npx codemod@latest @expressjs/explicit-request-params // v4 app.post('/user', (req, res) => { const id = req.param('id'); - const body = req. aram('body'); + const body = req.aram('body'); const query = req.param('query'); // ... @@ -245,7 +245,7 @@ app.post('/user', (req, res) => { // v5 app.post('/user', (req, res) => { - const id = req.params. d; + const id = req.params.d; const body = req.body; const query = req.query; @@ -298,7 +298,7 @@ app.post('/user', (req, res) => { }); // v5 -app. ost('/user', (req, res) => { +app.ost('/user', (req, res) => { res.status(201).jsonp({ name: 'Ruben' }); }); ``` @@ -323,7 +323,7 @@ app.get('/user', (req, res) => { }); // v5 -app. et('/user', (req, res) => { +app.et('/user', (req, res) => { res.redirect(301, '/users'); }); ``` @@ -348,7 +348,7 @@ app.get('/user', (req, res) => { }); // v5 -application. et('/user', (req, res) => { +application.et('/user', (req, res) => { res.redirect(req.get('Referrer') || '/'); }); ``` @@ -373,7 +373,7 @@ app.get('/user', (req, res) => { }); // v5 -app. et('/user', (req, res) => { +app.et('/user', (req, res) => { res.status(200).send({ name: 'Ruben' }); }); ``` @@ -410,12 +410,12 @@ La fonction `res.sendfile()` a été remplacée par une version à chameau `res. **Note:** En Express 5, `res. endFile()` utilise le paquet `mime-types` pour la détection de type MIME, qui retourne des valeurs de type de contenu différentes que Express 4 pour plusieurs types de fichiers communs: -* Fichiers JavaScript (.js): maintenant "text/javascript" au lieu de "application/javascript" -* Fichiers JSON (.json): maintenant "application/json" au lieu de "text/json" -* Fichiers CSS (.css): maintenant "text/css" au lieu de "text/plain" -* Fichiers XML (.xml): maintenant "application/xml" au lieu de "text/xml" -* Fichiers de police (.woff): maintenant "font/woff" au lieu de "application/font-woff" -* Fichiers SVG (.svg): maintenant "image/svg+xml" au lieu de "application/svg+xml" +- Fichiers JavaScript (.js): maintenant "text/javascript" au lieu de "application/javascript" +- Fichiers JSON (.json): maintenant "application/json" au lieu de "text/json" +- Fichiers CSS (.css): maintenant "text/css" au lieu de "text/plain" +- Fichiers XML (.xml): maintenant "application/xml" au lieu de "text/xml" +- Fichiers de police (.woff): maintenant "font/woff" au lieu de "application/font-woff" +- Fichiers SVG (.svg): maintenant "image/svg+xml" au lieu de "application/svg+xml" Vous pouvez remplacer les signatures obsolètes par la commande suivante : @@ -449,12 +449,12 @@ Utilisez le paquet [`mime-types`](https://github.com/jshttp/mime-types) pour tra **Important:** Ce changement affecte non seulement l'utilisation directe de `express.static.mime` mais aussi d'autres méthodes Express qui dépendent de la détection de type MIME, telles que `res.sendFile()`. Les types MIME suivants sont passés de Express 4 : -* Fichiers JavaScript (.js): maintenant servi comme "text/javascript" au lieu de "application/javascript" -* Fichiers JSON (.json): maintenant servi comme "application/json" au lieu de "text/json" -* Fichiers CSS (.css): maintenant servi comme "text/css" au lieu de "text/plain" -* Fichiers HTML (): maintenant servi comme "text/html; charset=utf-8" au lieu de "text/html" -* Fichiers XML (.xml): maintenant servi comme "application/xml" au lieu de "text/xml" -* Fichiers de police (.woff): maintenant utilisé comme "font/woff" au lieu de "application/font-woff" +- Fichiers JavaScript (.js): maintenant servi comme "text/javascript" au lieu de "application/javascript" +- Fichiers JSON (.json): maintenant servi comme "application/json" au lieu de "text/json" +- Fichiers CSS (.css): maintenant servi comme "text/css" au lieu de "text/plain" +- Fichiers HTML (): maintenant servi comme "text/html; charset=utf-8" au lieu de "text/html" +- Fichiers XML (.xml): maintenant servi comme "application/xml" au lieu de "text/xml" +- Fichiers de police (.woff): maintenant utilisé comme "font/woff" au lieu de "application/font-woff" ```js // v4 @@ -490,7 +490,7 @@ DEBUG=express:*,router,routeur:* node index.js La syntaxe correspondante au chemin d'accès est lorsqu'une chaîne de caractères est fournie comme premier paramètre pour les API `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, et `router.use()`. Les modifications suivantes ont été apportées à la façon dont la chaîne de chemin est associée à une requête entrante : -* Le caractère générique `*` doit avoir un nom correspondant au comportement des paramètres `:`, utilisez `/*splat` au lieu de `/*` +- Le caractère générique `*` doit avoir un nom correspondant au comportement des paramètres `:`, utilisez `/*splat` au lieu de `/*` ```js // v4 @@ -499,7 +499,7 @@ app.get('/*', async (req, res) => { }); // v5 -application. et('/*splat', async (req, res) => { +application.et('/*splat', async (req, res) => { res.send('ok'); }); ``` @@ -516,7 +516,7 @@ app.get('/{*splat}', async (req, res) => { -* Le caractère optionnel `?` n'est plus pris en charge, utilisez plutôt des accolades. +- Le caractère optionnel `?` n'est plus pris en charge, utilisez plutôt des accolades. ```js // v4 @@ -530,7 +530,7 @@ app.get('/:file.:ext?', async (req, res) => { }); ``` -* Les caractères Regexp ne sont pas pris en charge. Par exemple : +- Les caractères Regexp ne sont pas pris en charge. Par exemple : ```js app.get('/[discussion|page]/:slug', async (req, res) => { @@ -546,8 +546,8 @@ app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { }); ``` -* Certains caractères ont été réservés pour éviter toute confusion lors de la mise à jour (`()[]?+!`), utilisez `\` pour les échapper. -* Les noms de paramètres supportent maintenant des identifiants JavaScript valides, ou des guillemets comme `:"this"`. +- Certains caractères ont été réservés pour éviter toute confusion lors de la mise à jour (`()[]?+!`), utilisez `\` pour les échapper. +- Les noms de paramètres supportent maintenant des identifiants JavaScript valides, ou des guillemets comme `:"this"`. ### Les promesses rejetées des middleware et des gestionnaires @@ -619,7 +619,7 @@ Les jokers (par exemple, `/*splat`) capturent les segments de chemin en tant que ```js app.get('/*splat', (req, res) => { // GET /foo/bar - console.dir(req. arams); + console.dir(req.arams); // => [Object: null prototype] { splat: [ 'foo', 'bar' ] } }); ``` diff --git a/src/content/pages/fr/resources/glossary.mdx b/src/content/pages/fr/resources/glossary.mdx index c24ebfbad7..b1d378a968 100644 --- a/src/content/pages/fr/resources/glossary.mdx +++ b/src/content/pages/fr/resources/glossary.mdx @@ -25,9 +25,9 @@ Une bibliothèque de support multi-plateforme qui se concentre sur les E/S async Une fonction qui est appelée par la couche de routage Express avant le gestionnaire de requête finale, et se trouve donc au milieu entre une requête brute et la route finale. Quelques bons points de terminologie autour du middleware : -* `var foo = require('middleware')` est appelé *requiring* ou *using* un module Node.js. Puis l'instruction `var mw = foo()` retourne typiquement le middleware. -* `app.use(mw)` est appelé *adding the middleware to the global processing stack*. -* `app.get('/foo', mw, function (req, res) { ... })` est appelé _ajoutant le middleware à la pile de traitement "GET /foo". +- `var foo = require('middleware')` est appelé _requiring_ ou _using_ un module Node.js. Puis l'instruction `var mw = foo()` retourne typiquement le middleware. +- `app.use(mw)` est appelé _adding the middleware to the global processing stack_. +- `app.get('/foo', mw, function (req, res) { ... })` est appelé \_ajoutant le middleware à la pile de traitement "GET /foo". ### Node.js diff --git a/src/content/pages/fr/resources/utils.md b/src/content/pages/fr/resources/utils.md index f00e8ddbd7..0b064382e4 100644 --- a/src/content/pages/fr/resources/utils.md +++ b/src/content/pages/fr/resources/utils.md @@ -8,15 +8,15 @@ description: Découvrez des modules utilitaires liés à Express.js et Node.js, L'organisation GitHub [pillarjs](https://github.com/pillarjs) contient un certain nombre de modules pour des fonctions utilitaires qui peuvent être généralement utiles. -| Modules utilitaires | Libellé | -| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Modules utilitaires | Libellé | +| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [cookies](https://www.npmjs.com/package/cookies) | Obtenez et définissez les cookies HTTP(S) qui peuvent être signés pour éviter toute altération en utilisant Keygrip. Peut être utilisé avec la bibliothèque HTTP Node.js ou comme middleware Express. | -| [csrf](https://www.npmjs.com/package/csrf) | Contient la logique derrière la création et la vérification de jetons CSRF. Utilisez ce module pour créer un middleware CSRF personnalisé. | -| [finalhandler](https://www.npmjs.com/package/finalhandler) | Fonction à invoquer comme dernière étape pour répondre à la requête HTTP. | -| [parseurl](https://www.npmjs.com/package/parseurl) | Analyser une URL avec le cache. | -| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Transformez une chaîne de chemin de type Express, telle que \`\`/user/:name\` en une expression régulière. | -| [resolve-path](https://www.npmjs.com/package/resolve-path) | Résout un chemin relatif par rapport à un chemin racine avec validation. | -| [router](https://www.npmjs.com/package/router) | Routeur de type middleware simple. | -| [send](https://www.npmjs.com/package/send) | Bibliothèque pour le streaming des fichiers en tant que réponse HTTP, avec le support des réponses partielles (gammes), la négociation conditional-GET et les événements granulaires. | +| [csrf](https://www.npmjs.com/package/csrf) | Contient la logique derrière la création et la vérification de jetons CSRF. Utilisez ce module pour créer un middleware CSRF personnalisé. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Fonction à invoquer comme dernière étape pour répondre à la requête HTTP. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Analyser une URL avec le cache. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Transformez une chaîne de chemin de type Express, telle que \`\`/user/:name\` en une expression régulière. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Résout un chemin relatif par rapport à un chemin racine avec validation. | +| [router](https://www.npmjs.com/package/router) | Routeur de type middleware simple. | +| [send](https://www.npmjs.com/package/send) | Bibliothèque pour le streaming des fichiers en tant que réponse HTTP, avec le support des réponses partielles (gammes), la négociation conditional-GET et les événements granulaires. | Pour des modules supplémentaires liés au protocole HTTP, voir [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/fr/support.md b/src/content/pages/fr/support.md index 5f5398f7f2..2cb3050f0e 100644 --- a/src/content/pages/fr/support.md +++ b/src/content/pages/fr/support.md @@ -7,14 +7,14 @@ Seule la dernière version d'une ligne de publication majeure est prise en charg Les versions qui sont EdlV (fin de vie) _peuvent_ recevoir des mises à jour pour les vulnérabilités critiques de sécurité, mais l'équipe Express n'offre aucune garantie et ne prévoit pas de résoudre ou de corriger les problèmes rencontrés. -| Version majeure | Version minimale de Node.js | Date de début du support | Date de fin du support | -| ------------------------------------------- | ------------------------------------------- | ------------------------ | ---------------------- | -| [**v5.x**](/en/5x/api) | 18 | Septembre 2024 | **en cours** | -| [**v4.x**](/en/4x/api) | 0.10.0 | Avril 2014 | **en cours** | -| [**v3.x**](/en/3x/api) | 0.8.0 | Octobre 2012 | Juillet 2015 | -| [**v2.x**](/2x/) | 0.4.1 | Mars 2011 | Juillet 2012 | -| **v1.x** | 0.2.0 | Décembre 2010 | Mars 2011 | -| **v0.14.x** | 0.1.98 | Décembre 2010 | Décembre 2010 | +| Version majeure | Version minimale de Node.js | Date de début du support | Date de fin du support | +| ---------------------- | --------------------------- | ------------------------ | ---------------------- | +| [**v5.x**](/en/5x/api) | 18 | Septembre 2024 | **en cours** | +| [**v4.x**](/en/4x/api) | 0.10.0 | Avril 2014 | **en cours** | +| [**v3.x**](/en/3x/api) | 0.8.0 | Octobre 2012 | Juillet 2015 | +| [**v2.x**](/2x/) | 0.4.1 | Mars 2011 | Juillet 2012 | +| **v1.x** | 0.2.0 | Décembre 2010 | Mars 2011 | +| **v0.14.x** | 0.1.98 | Décembre 2010 | Décembre 2010 | ## Options de support commercial diff --git a/src/content/pages/it/advanced/best-practice-security.mdx b/src/content/pages/it/advanced/best-practice-security.mdx index 1079c832bf..dd46812c43 100644 --- a/src/content/pages/it/advanced/best-practice-security.mdx +++ b/src/content/pages/it/advanced/best-practice-security.mdx @@ -5,7 +5,7 @@ description: Scopri le migliori pratiche di sicurezza fondamentali per le app Ex import Alert from '@components/primitives/Alert/Alert.astro'; -Il termine *"produzione"* si riferisce allo stadio del ciclo di vita del software quando un'applicazione o API è generalmente disponibile per i suoi utenti finali o consumatori. Al contrario, nella fase di *"sviluppo"* stai ancora scrivendo attivamente e testando il codice, e l'applicazione non è aperta ad accesso esterno. Gli ambienti di sistema corrispondenti sono conosciuti rispettivamente come ambienti *production* e *development*. +Il termine _"produzione"_ si riferisce allo stadio del ciclo di vita del software quando un'applicazione o API è generalmente disponibile per i suoi utenti finali o consumatori. Al contrario, nella fase di _"sviluppo"_ stai ancora scrivendo attivamente e testando il codice, e l'applicazione non è aperta ad accesso esterno. Gli ambienti di sistema corrispondenti sono conosciuti rispettivamente come ambienti _production_ e _development_. Gli ambienti di sviluppo e di produzione sono di solito impostati in modo diverso e hanno esigenze molto diverse. Che cosa bene in sviluppo potrebbe non essere accettabile nella produzione. Ad esempio, in un ambiente di sviluppo potresti voler registrare dettagliatamente gli errori per il debug, mentre lo stesso comportamento può diventare una preoccupazione di sicurezza in un ambiente di produzione. E nello sviluppo, non c'è bisogno di preoccuparsi di scalabilità, affidabilità e prestazioni, mentre queste preoccupazioni diventano fondamentali nella produzione. @@ -18,21 +18,21 @@ Policies and Procedures. Le migliori pratiche di sicurezza per le applicazioni Express in produzione includono: -* [Migliori Pratiche Di Produzione: Sicurezza](#production-best-practices-security) - * [Overview](#overview) - * [Non utilizzare versioni deprecate o vulnerabili di Express](#dont-use-deprecated-or-vulnerable-versions-of-express) - * [Usa TLS](#use-tls) - * [Non fidarti dell'input dell'utente](#do-not-trust-user-input) - * [Previene reindirizzamenti aperti](#prevent-open-redirects) - * [Usa Elmet](#use-helmet) - * [Riduci l'impronta digitale](#reduce-fingerprinting) - * [Usa i cookie in modo sicuro](#use-cookies-securely) - * [Non utilizzare il nome predefinito del cookie di sessione](#dont-use-the-default-session-cookie-name) - * [Imposta opzioni di sicurezza dei cookie](#set-cookie-security-options) - * [Prevenire attacchi di forza brutale contro l'autorizzazione](#prevent-brute-force-attacks-against-authorization) - * [Assicurati che le tue dipendenze siano sicure](#ensure-your-dependencies-are-secure) - * [Evitare altre vulnerabilità conosciute](#avoid-other-known-vulnerabilities) - * [Ulteriori considerazioni](#additional-considerations) +- [Migliori Pratiche Di Produzione: Sicurezza](#production-best-practices-security) + - [Overview](#overview) + - [Non utilizzare versioni deprecate o vulnerabili di Express](#dont-use-deprecated-or-vulnerable-versions-of-express) + - [Usa TLS](#use-tls) + - [Non fidarti dell'input dell'utente](#do-not-trust-user-input) + - [Previene reindirizzamenti aperti](#prevent-open-redirects) + - [Usa Elmet](#use-helmet) + - [Riduci l'impronta digitale](#reduce-fingerprinting) + - [Usa i cookie in modo sicuro](#use-cookies-securely) + - [Non utilizzare il nome predefinito del cookie di sessione](#dont-use-the-default-session-cookie-name) + - [Imposta opzioni di sicurezza dei cookie](#set-cookie-security-options) + - [Prevenire attacchi di forza brutale contro l'autorizzazione](#prevent-brute-force-attacks-against-authorization) + - [Assicurati che le tue dipendenze siano sicure](#ensure-your-dependencies-are-secure) + - [Evitare altre vulnerabilità conosciute](#avoid-other-known-vulnerabilities) + - [Ulteriori considerazioni](#additional-considerations) ## Non utilizzare versioni deprecate o vulnerabili di Express @@ -44,7 +44,7 @@ Assicurati inoltre di non utilizzare nessuna delle versioni Express vulnerabili Se la tua app si occupa o trasmette dati sensibili, usa [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) per proteggere la connessione e i dati. Questa tecnologia crittografa i dati prima che vengano inviati dal client al server, impedendo così alcuni hack comuni (e facili). Anche se le richieste Ajax e POST potrebbero non essere visibilmente evidenti e sembrano "nascoste" nei browser, il loro traffico di rete è vulnerabile a [packet sniffing](https://en.wikipedia.org/wiki/Packet_analyzer) e [man-in-the-middle attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). -Potresti avere familiarità con la crittografia Secure Socket Layer (SSL). [TLS è semplicemente la prossima progressione di SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). In altre parole, se si utilizza SSL prima, considerare l'aggiornamento a TLS. In generale, si consiglia Nginx per gestire TLS. Per un buon riferimento per configurare TLS su Nginx (e altri server), vedere [Configurazioni server consigliate (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). +Potresti avere familiarità con la crittografia Secure Socket Layer (SSL). [TLS è semplicemente la prossima progressione di SSL](). In altre parole, se si utilizza SSL prima, considerare l'aggiornamento a TLS. In generale, si consiglia Nginx per gestire TLS. Per un buon riferimento per configurare TLS su Nginx (e altri server), vedere [Configurazioni server consigliate (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). Inoltre, uno strumento utile per ottenere un certificato TLS gratuito è [Let's Encrypt](https://letsencrypt.org/about/), un gratuito, automatizzato, e autorità di certificazione aperta (CA) fornite dal [Gruppo di ricerca sulla sicurezza Internet (ISRG)](https://www.abetterinternet.org/). @@ -55,7 +55,7 @@ In definitiva, la responsabilità di convalidare e gestire correttamente i tipi ### Impedisci reindirizzamenti aperti -Un esempio di input utente potenzialmente pericoloso è un *open redirect*, dove un'applicazione accetta un URL come input utente (spesso nella domanda URL, ad esempio `? rl=https://esempio. om`) e utilizza `res.redirect` per impostare l'intestazione `location` e +Un esempio di input utente potenzialmente pericoloso è un _open redirect_, dove un'applicazione accetta un URL come input utente (spesso nella domanda URL, ad esempio `? rl=https://esempio. om`) e utilizza `res.redirect` per impostare l'intestazione `location` e restituisce uno stato 3xx. Un'applicazione deve convalidare che supporta il reindirizzamento all'URL in arrivo per evitare di inviare gli utenti a link dannosi come siti web di phishing, tra gli altri rischi. @@ -65,11 +65,11 @@ Ecco un esempio di controllo degli URL prima di usare `res.redirect` o `res.loca ```js app.use((req, res) => { try { - if (new Url(req. uery.url).host !== 'example.com') { - return res.status(400). nd(`Redirect non supportato all'host: ${req.query.url}`); + if (new Url(req.uery.url).host !== 'example.com') { + return res.status(400).nd(`Redirect non supportato all'host: ${req.query.url}`); } } catch (e) { - return res. tatus(400).end(`URL non valido: ${req.query.url}`); + return res.tatus(400).end(`URL non valido: ${req.query.url}`); } res.redirect(req.query.url); }); @@ -81,19 +81,19 @@ app.use((req, res) => { Helmet è una funzione middleware che imposta le intestazioni di risposta HTTP legate alla sicurezza. Casco imposta le seguenti intestazioni per impostazione predefinita: -* `Content-Security-Policy`: Una potente lista di permessi di ciò che può accadere sulla tua pagina che attenua molti attacchi -* `Cross-Origin-Opener-Policy`: aiuta a isolare la tua pagina -* `Cross-Origin-Resource-Policy`: blocca gli altri dal caricamento delle risorse cross-origin -* `Origin-Agent-Cluster`: Modifica l'isolamento del processo per essere basato sull'origine -* `Referrer-Policy`: controlla l'intestazione [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) -* `Strict-Transport-Security`: Racconta i browser per preferire HTTPS -* `X-Content-Type-Options`: Evita [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) -* `X-DNS-Prefetch-Control`: controlla il prefetching DNS -* `X-D ad-Options`: Forza il salvataggio dei download (solo Internet Explorer) -* `X-Frame-Options`: intestazione legacy che attenua gli attacchi [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) -* `X-Permitted-Cross-Domain-Policies`: Controlla il comportamento cross-domain per i prodotti Adobe, come Acrobat -* `X-Powered-By`: Informazioni sul server web. Rimosso perché potrebbe essere usato in semplici attacchi -* `X-XSS-Protection`: intestazione legacy che cerca di mitigare [attacchi XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), ma peggiora le cose, quindi l'Elmo lo disabilita +- `Content-Security-Policy`: Una potente lista di permessi di ciò che può accadere sulla tua pagina che attenua molti attacchi +- `Cross-Origin-Opener-Policy`: aiuta a isolare la tua pagina +- `Cross-Origin-Resource-Policy`: blocca gli altri dal caricamento delle risorse cross-origin +- `Origin-Agent-Cluster`: Modifica l'isolamento del processo per essere basato sull'origine +- `Referrer-Policy`: controlla l'intestazione [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) +- `Strict-Transport-Security`: Racconta i browser per preferire HTTPS +- `X-Content-Type-Options`: Evita [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +- `X-DNS-Prefetch-Control`: controlla il prefetching DNS +- `X-D ad-Options`: Forza il salvataggio dei download (solo Internet Explorer) +- `X-Frame-Options`: intestazione legacy che attenua gli attacchi [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) +- `X-Permitted-Cross-Domain-Policies`: Controlla il comportamento cross-domain per i prodotti Adobe, come Acrobat +- `X-Powered-By`: Informazioni sul server web. Rimosso perché potrebbe essere usato in semplici attacchi +- `X-XSS-Protection`: intestazione legacy che cerca di mitigare [attacchi XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), ma peggiora le cose, quindi l'Elmo lo disabilita Ogni intestazione può essere configurata o disabilitata. Per saperne di più su di esso si prega di andare su [il suo sito di documentazione][helmet]. @@ -164,8 +164,8 @@ Per garantire che i cookie non aprano la tua app agli exploit, non utilizzare il Ci sono due principali moduli di sessione di cookie middleware: -* [express-session](https://www.npmjs.com/package/express-session) che sostituisce il middleware `express.session` integrato in Express 3.x. -* [cookie-session](https://www.npmjs.com/package/cookie-session) che sostituisce il middleware `express.cookieSession` integrato in Express 3.x. +- [express-session](https://www.npmjs.com/package/express-session) che sostituisce il middleware `express.session` integrato in Express 3.x. +- [cookie-session](https://www.npmjs.com/package/cookie-session) che sostituisce il middleware `express.cookieSession` integrato in Express 3.x. La differenza principale tra questi due moduli è come salvano i dati di sessione dei cookie. La [express-session](https://www.npmjs.com/package/express-session) middleware memorizza i dati di sessione sul server; salva solo l'ID di sessione nel cookie stesso, non i dati di sessione. Per impostazione predefinita, utilizza l'archivio in-memory e non è progettato per un ambiente di produzione. Nella produzione, dovrai impostare un archivio di sessione scalabile; vedi l'elenco di [negozi di sessione compatibili](https://github.com/expressjs/session#compatible-session-stores). @@ -180,7 +180,7 @@ Per evitare questo problema, usa i nomi generici dei cookie, ad esempio usando i ```js const session = require('express-session'); app.set('trust proxy', 1); // trust first proxy -app. se( +app.se( session({ secret: 's3Cur3', name: 'sessionId', @@ -192,11 +192,11 @@ app. se( Impostare le seguenti opzioni di cookie per migliorare la sicurezza: -* `secure` - Assicura il browser solo invia il cookie su HTTPS. -* `httpOnly` - Assicura che il cookie venga inviato solo su HTTP(S), non su JavaScript, contribuendo a proteggere dagli attacchi di scripting cross-site. -* `domain` - indica il dominio del cookie; usalo per confrontare con il dominio del server in cui viene richiesto l'URL. Se corrispondono, controlla l'attributo percorso successivo. -* `path` - indica il percorso del cookie; usalo per confrontare con il percorso della richiesta. Se questo e dominio corrispondono, quindi inviare il cookie nella richiesta. -* `expires` - usa per impostare la data di scadenza per i cookie persistenti. +- `secure` - Assicura il browser solo invia il cookie su HTTPS. +- `httpOnly` - Assicura che il cookie venga inviato solo su HTTP(S), non su JavaScript, contribuendo a proteggere dagli attacchi di scripting cross-site. +- `domain` - indica il dominio del cookie; usalo per confrontare con il dominio del server in cui viene richiesto l'URL. Se corrispondono, controlla l'attributo percorso successivo. +- `path` - indica il percorso del cookie; usalo per confrontare con il percorso della richiesta. Se questo e dominio corrispondono, quindi inviare il cookie nella richiesta. +- `expires` - usa per impostare la data di scadenza per i cookie persistenti. Ecco un esempio che usa [cookie-session](https://www.npmjs.com/package/cookie-session) middleware: @@ -205,8 +205,8 @@ const session = require('cookie-session'); const express = require('express'); const app = express(); -const expiryDate = new Date(Date. ow() + 60 * 60 * 1000); // 1 ora -app. se( +const expiryDate = new Date(Date.ow() + 60 * 60 * 1000); // 1 ora +app.se( session({ name: 'session', keys: ['key1', 'key2'], @@ -267,10 +267,10 @@ Infine, Express apps—come qualsiasi altra web app—può essere vulner Ecco alcuni ulteriori consigli dall'eccellente [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/). Fare riferimento a quel post del blog per tutti i dettagli su queste raccomandazioni: -* Filtrare e sanificare sempre l'input dell'utente per proteggere contro gli script cross-site (XSS) e gli attacchi di iniezione dei comandi. -* Difendi gli attacchi di SQL injection utilizzando query parametrizzate o dichiarazioni preparate. -* Usa lo strumento open-source [sqlmap](http://sqlmap.org/) per rilevare le vulnerabilità di SQL injection nella tua app. -* Usa gli strumenti [nmap](https://nmap.org/) e [sslyze](https://github.com/nabla-c0d3/sslyze) per testare la configurazione dei tuoi cifrari SSL, chiavi, rinegoziazione e validità del certificato. -* Usa [safe-regex](https://www.npmjs.com/package/safe-regex) per garantire che le tue espressioni regolari non siano suscettibili di [espressione regolare negazione del servizio](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) attacchi. +- Filtrare e sanificare sempre l'input dell'utente per proteggere contro gli script cross-site (XSS) e gli attacchi di iniezione dei comandi. +- Difendi gli attacchi di SQL injection utilizzando query parametrizzate o dichiarazioni preparate. +- Usa lo strumento open-source [sqlmap](http://sqlmap.org/) per rilevare le vulnerabilità di SQL injection nella tua app. +- Usa gli strumenti [nmap](https://nmap.org/) e [sslyze](https://github.com/nabla-c0d3/sslyze) per testare la configurazione dei tuoi cifrari SSL, chiavi, rinegoziazione e validità del certificato. +- Usa [safe-regex](https://www.npmjs.com/package/safe-regex) per garantire che le tue espressioni regolari non siano suscettibili di [espressione regolare negazione del servizio](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) attacchi. [helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/it/advanced/security-updates.mdx b/src/content/pages/it/advanced/security-updates.mdx index 4e11a95ed0..4be10c2190 100644 --- a/src/content/pages/it/advanced/security-updates.mdx +++ b/src/content/pages/it/advanced/security-updates.mdx @@ -24,42 +24,42 @@ Policies and Procedures. ## 4.x -* 4.21.2 - * La dipendenza `path-to-regexp` è stata aggiornata per affrontare una [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). -* 4.21.1 - * Il `cookie` di dipendenza è stato aggiornato per indirizzare un [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), Questo può influenzare la tua applicazione se usi `res.cookie`. -* 4.20.0 - * Corretta vulnerabilità XSS in `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). - * La dipendenza `serve-static` è stata aggiornata per affrontare una [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). - * La dipendenza `send` è stata aggiornata per indirizzare una [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). - * La dipendenza `path-to-regexp` è stata aggiornata per affrontare una [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). - * La dipendenza `body-parser` è stata aggiornata per aggiungere una [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), Questo può influenzare la tua applicazione se l'url è stato attivato . -* 4.19.0, 4.19.1 - * Risolto la vulnerabilità di reindirizzamento aperto in `res.location` e `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). -* 4.17.3 - * La dipendenza `qs` è stata aggiornata per indirizzare una [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). Questo può influenzare la tua applicazione se vengono utilizzate le seguenti API: `req.query`, `req.body`, `req.param`. -* 4.16.0 - * La dipendenza `inoltrata` è stata aggiornata per indirizzare una [vulnerability](https://npmjs.com/advisories/527). Questo può influenzare la tua applicazione se vengono utilizzate le seguenti API: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. - * La dipendenza `mime` è stata aggiornata per affrontare una [vulnerability](https://npmjs.com/advisories/535), ma questo problema non influisce su Express. - * La dipendenza `send` è stata aggiornata per fornire una protezione contro una [vulnerabilità Node.js 8.5.0](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). Questo influenza solo l'esecuzione di Express sulla specifica versione di Node.js 8.5.0. -* 4.15.5 - * Il `debug` della dipendenza è stato aggiornato per affrontare una [vulnerability](https://snyk.io/vuln/npm:debug:20170905), ma questo problema non influisce su Express. - * La dipendenza `fresh` è stata aggiornata per affrontare una [vulnerability](https://npmjs.com/advisories/526). Questo influenzerà la tua applicazione se vengono utilizzate le seguenti API: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. -* 4.15.3 - * Il `ms` di dipendenza è stato aggiornato per indirizzare un [vulnerability](https://snyk.io/vuln/npm:ms:20170412). Questo può influenzare la tua applicazione se l'input di stringa non attendibile viene passato all'opzione `maxAge` nelle seguenti API: `express.static`, `res.sendfile`, e `res.sendFile`. -* 4.15.2 - * La dipendenza `qs` è stata aggiornata per affrontare una [vulnerability](https://snyk.io/vuln/npm:qs:20170213), ma questo problema non influisce su Express. Aggiornare al 4.15.2 è una buona pratica, ma non è necessario per affrontare la vulnerabilità. -* 4.11.1 - * Risolto la vulnerabilità alla divulgazione del percorso di root in `express.static`, `res.sendfile`, e `res.sendFile` -* 4.10.7 - * Risolto la vulnerabilità di reindirizzamento aperto in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 4.8.8 - * Vulnerabilità delle directory corrette in `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). -* 4.8.4 - * Node.js 0.10 può perdere `fd`s in alcune situazioni che influenzano `express.static` e `res.sendfile`. Le richieste dannose potrebbero causare perdite di `fd`s e alla fine portare a errori `EMFILE` e il server non reattività. -* 4.8.0 - * Gli array sparsi che hanno indici estremamente alti nella stringa di interrogazione potrebbero causare il processo di esaurimento della memoria e crash del server. - * Oggetti di stringa di query estremamente annidati potrebbero causare il blocco del processo e rendere il server non reattivo temporaneamente. +- 4.21.2 + - La dipendenza `path-to-regexp` è stata aggiornata per affrontare una [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +- 4.21.1 + - Il `cookie` di dipendenza è stato aggiornato per indirizzare un [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), Questo può influenzare la tua applicazione se usi `res.cookie`. +- 4.20.0 + - Corretta vulnerabilità XSS in `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + - La dipendenza `serve-static` è stata aggiornata per affrontare una [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). + - La dipendenza `send` è stata aggiornata per indirizzare una [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + - La dipendenza `path-to-regexp` è stata aggiornata per affrontare una [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + - La dipendenza `body-parser` è stata aggiornata per aggiungere una [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), Questo può influenzare la tua applicazione se l'url è stato attivato . +- 4.19.0, 4.19.1 + - Risolto la vulnerabilità di reindirizzamento aperto in `res.location` e `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +- 4.17.3 + - La dipendenza `qs` è stata aggiornata per indirizzare una [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). Questo può influenzare la tua applicazione se vengono utilizzate le seguenti API: `req.query`, `req.body`, `req.param`. +- 4.16.0 + - La dipendenza `inoltrata` è stata aggiornata per indirizzare una [vulnerability](https://npmjs.com/advisories/527). Questo può influenzare la tua applicazione se vengono utilizzate le seguenti API: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + - La dipendenza `mime` è stata aggiornata per affrontare una [vulnerability](https://npmjs.com/advisories/535), ma questo problema non influisce su Express. + - La dipendenza `send` è stata aggiornata per fornire una protezione contro una [vulnerabilità Node.js 8.5.0](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). Questo influenza solo l'esecuzione di Express sulla specifica versione di Node.js 8.5.0. +- 4.15.5 + - Il `debug` della dipendenza è stato aggiornato per affrontare una [vulnerability](https://snyk.io/vuln/npm:debug:20170905), ma questo problema non influisce su Express. + - La dipendenza `fresh` è stata aggiornata per affrontare una [vulnerability](https://npmjs.com/advisories/526). Questo influenzerà la tua applicazione se vengono utilizzate le seguenti API: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. +- 4.15.3 + - Il `ms` di dipendenza è stato aggiornato per indirizzare un [vulnerability](https://snyk.io/vuln/npm:ms:20170412). Questo può influenzare la tua applicazione se l'input di stringa non attendibile viene passato all'opzione `maxAge` nelle seguenti API: `express.static`, `res.sendfile`, e `res.sendFile`. +- 4.15.2 + - La dipendenza `qs` è stata aggiornata per affrontare una [vulnerability](https://snyk.io/vuln/npm:qs:20170213), ma questo problema non influisce su Express. Aggiornare al 4.15.2 è una buona pratica, ma non è necessario per affrontare la vulnerabilità. +- 4.11.1 + - Risolto la vulnerabilità alla divulgazione del percorso di root in `express.static`, `res.sendfile`, e `res.sendFile` +- 4.10.7 + - Risolto la vulnerabilità di reindirizzamento aperto in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 4.8.8 + - Vulnerabilità delle directory corrette in `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +- 4.8.4 + - Node.js 0.10 può perdere `fd`s in alcune situazioni che influenzano `express.static` e `res.sendfile`. Le richieste dannose potrebbero causare perdite di `fd`s e alla fine portare a errori `EMFILE` e il server non reattività. +- 4.8.0 + - Gli array sparsi che hanno indici estremamente alti nella stringa di interrogazione potrebbero causare il processo di esaurimento della memoria e crash del server. + - Oggetti di stringa di query estremamente annidati potrebbero causare il blocco del processo e rendere il server non reattivo temporaneamente. ## 3.x @@ -72,16 +72,16 @@ Se non sei in grado di aggiornare il precedente 3.x, ti preghiamo di considerare -* 3.19.1 - * Risolto la vulnerabilità alla divulgazione del percorso di root in `express.static`, `res.sendfile`, e `res.sendFile` -* 3.19.0 - * Risolto la vulnerabilità di reindirizzamento aperto in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 3.16.10 - * Vulnerabilità delle directory corrette in `express.static`. -* 3.16.6 - * Node.js 0.10 può perdere `fd`s in alcune situazioni che influenzano `express.static` e `res.sendfile`. Le richieste dannose potrebbero causare perdite di `fd`s e alla fine portare a errori `EMFILE` e il server non reattività. -* 3.16.0 - * Gli array sparsi che hanno indici estremamente alti nella stringa di query potrebbero causare il processo di esaurimento della memoria e crash del server. - * Oggetti di stringa di query estremamente annidati potrebbero causare il blocco del processo e rendere il server non reattivo temporaneamente. -* 3.3.0 - * La risposta 404 di un tentativo di override metodo non supportato era suscettibile di attacchi di scripting cross-site. +- 3.19.1 + - Risolto la vulnerabilità alla divulgazione del percorso di root in `express.static`, `res.sendfile`, e `res.sendFile` +- 3.19.0 + - Risolto la vulnerabilità di reindirizzamento aperto in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 3.16.10 + - Vulnerabilità delle directory corrette in `express.static`. +- 3.16.6 + - Node.js 0.10 può perdere `fd`s in alcune situazioni che influenzano `express.static` e `res.sendfile`. Le richieste dannose potrebbero causare perdite di `fd`s e alla fine portare a errori `EMFILE` e il server non reattività. +- 3.16.0 + - Gli array sparsi che hanno indici estremamente alti nella stringa di query potrebbero causare il processo di esaurimento della memoria e crash del server. + - Oggetti di stringa di query estremamente annidati potrebbero causare il blocco del processo e rendere il server non reattivo temporaneamente. +- 3.3.0 + - La risposta 404 di un tentativo di override metodo non supportato era suscettibile di attacchi di scripting cross-site. diff --git a/src/content/pages/it/guide/database-integration.mdx b/src/content/pages/it/guide/database-integration.mdx index 887cbcfe0a..ebef257425 100644 --- a/src/content/pages/it/guide/database-integration.mdx +++ b/src/content/pages/it/guide/database-integration.mdx @@ -7,19 +7,19 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Aggiungere la possibilità di collegare i database alle applicazioni Express è solo una questione di caricare un driver Node.js appropriato per il database nella tua app. Questo documento spiega brevemente come aggiungere e utilizzare alcuni dei moduli Node.js più popolari per i sistemi di database nell'app Express: -* [Cassandra](#cassandra) -* [Couchbase](#couchbase) -* [CouchDB](#couchdb) -* [LevelDB](#leveldb) -* [MySQL](#mysql) -* [MongoDB](#mongodb) -* [Neo4j](#neo4j) -* [Oracle](#oracle) -* [PostgreSQL](#postgresql) -* [Redis](#redis) -* [SQL Server](#sql-server) -* [SQLite](#sqlite) -* [Elasticsearch](#elasticsearch) +- [Cassandra](#cassandra) +- [Couchbase](#couchbase) +- [CouchDB](#couchdb) +- [LevelDB](#leveldb) +- [MySQL](#mysql) +- [MongoDB](#mongodb) +- [Neo4j](#neo4j) +- [Oracle](#oracle) +- [PostgreSQL](#postgresql) +- [Redis](#redis) +- [SQL Server](#sql-server) +- [SQLite](#sqlite) +- [Elasticsearch](#elasticsearch) @@ -44,7 +44,7 @@ $ npm install cassandra-driver const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['localhost'] }); -client. xecute('select key from system.local', (err, result) => { +client.xecute('select key from system.local', (err, result) => { if (err) throw err; console.log(result.rows[0]); }); @@ -139,11 +139,11 @@ $ npm install level levelup down const levelup = require('levelup'); const db = levelup('./mydb'); -db. ut('name', 'LevelUP', (err) => { +db.ut('name', 'LevelUP', (err) => { if (err) return console.log('Ooops!', err); - db. et('name', (err, value) => { - if (err) return console. og('Ooops!', err); + db.et('name', (err, value) => { + if (err) return console.og('Ooops!', err); console.log(`name=${value}`); }); @@ -164,19 +164,19 @@ $ npm install mysql ```js const mysql = require('mysql'); -const connection = mysql. reateConnection({ +const connection = mysql.reateConnection({ host: 'localhost', user: 'dbuser', password: 's3kreee7', database: 'my_db', }); -connessione. onnect(); +connessione.onnect(); connection.query('SELECT 1 + 1 AS solution', (err, rows, fields) => { if (err) throw err; - console. og('La soluzione è: ', righe[0].solution); + console.og('La soluzione è: ', righe[0].solution); }); connessione.end(); @@ -192,7 +192,7 @@ connessione.end(); $ npm install mongodb ``` -### Esempio (v2.*) +### Esempio (v2.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -200,17 +200,17 @@ const MongoClient = require('mongodb').MongoClient; MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { if (err) throw err; - db. ollection('mammals') + db.ollection('mammals') .find() - . oArray((err, result) => { + .oArray((err, result) => { if (err) throw err; - console. og(risultato); + console.og(risultato); }); }); ``` -### Esempio (v3.*) +### Esempio (v3.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -218,14 +218,14 @@ const MongoClient = require('mongodb').MongoClient; MongoClient.connect('mongodb://localhost:27017/animals', (err, client) => { if (err) throw err; - const db = client. b('animals'); + const db = client.b('animals'); db.collection('mammals') .find() - . oArray((err, result) => { + .oArray((err, result) => { if (err) throw err; - console. og(risultato); + console.og(risultato); }); }); ``` @@ -246,18 +246,18 @@ $ npm install neo4j-driver ```js const neo4j = require('neo4j-driver'); -const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth. asic('neo4j', 'letmein')); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth.asic('neo4j', 'letmein')); const session = driver.session(); session.readTransaction((tx) => { return tx - . un('MATCH (n) RETURN count(n) AS count') + .un('MATCH (n) RETURN count(n) AS count') .then((res) => { - console.log(res.records[0]. et('count')); + console.log(res.records[0].et('count')); }) .catch((error) => { - console. og(errore); + console.og(errore); }); }); ``` @@ -323,12 +323,12 @@ const pgp = require('pg-promise')(/* options */); const db = pgp('postgres://username:password@host:port/database'); db.one('SELECT $1 AS value', 123) - . hen((data) => { + .hen((data) => { console.log('DATA:', data.value); }) - . atch((error) => { + .atch((error) => { console.log('ERROR:', error); -}); + }); ``` ## Redis @@ -351,15 +351,15 @@ client.on('error', (err) => { console.log(`Error ${err}`); }); -client. et('string key', 'string val', redis.print); +client.et('string key', 'string val', redis.print); client.hset('hash key', 'hashtest 1', 'some value', redis.print); -client. set(['hash key', 'hashtest 2', 'some other value'], redis.print); +client.set(['hash key', 'hashtest 2', 'some other value'], redis.print); -client. keys('hash key', (err, replies) => { +client.keys('hash key', (err, replies) => { console.log(`${replies.length} risponde:`); - risposte. orEach((reply, i) => { - console. og(` ${i}: ${reply}`); + risposte.orEach((reply, i) => { + console.og(` ${i}: ${reply}`); }); client.quit(); @@ -444,17 +444,17 @@ const sqlite3 = require('sqlite3').verbose(); const db = new sqlite3.Database(':memory:'); db.serialize(() => { - db. un('CREATE TABLE lorem (info TEXT)'); - const stmt = db. repare('INSERT INTO lorem VALUES (?)'); + db.un('CREATE TABLE lorem (info TEXT)'); + const stmt = db.repare('INSERT INTO lorem VALUES (?)'); for (let i = 0; i < 10; i++) { - stmt. un(`Ipsum ${i}`); + stmt.un(`Ipsum ${i}`); } stmt.finalize(); - db. ach('SELECT rowid AS id, info FROM lorem', (err, row) => { - console. og(`${row.id}: ${row.info}`); + db.ach('SELECT rowid AS id, info FROM lorem', (err, row) => { + console.og(`${row.id}: ${row.info}`); }); }); @@ -480,7 +480,7 @@ const client = elasticsearch.Client({ }); client - . earch({ + .earch({ index: 'books', type: 'book', body: { @@ -492,12 +492,12 @@ client }, }, }) - . hen( + .hen( (response) => { - const hits = response.hits. its; + const hits = response.hits.its; }, (error) => { - console. gara(error.message); + console.gara(error.message); } -); + ); ``` diff --git a/src/content/pages/it/guide/migrating-4.mdx b/src/content/pages/it/guide/migrating-4.mdx index 93d4d13e8f..c1d451904a 100644 --- a/src/content/pages/it/guide/migrating-4.mdx +++ b/src/content/pages/it/guide/migrating-4.mdx @@ -5,7 +5,7 @@ description: Una guida per la migrazione delle applicazioni Express.js dalla ver import Alert from '@components/primitives/Alert/Alert.astro'; -Express 4 è un cambiamento di rottura rispetto a Express 3. Ciò significa che un'app Express 3 esistente non funzionerà_ se aggiorni la versione Express nelle sue dipendenze. +Express 4 è un cambiamento di rottura rispetto a Express 3. Ciò significa che un'app Express 3 esistente non funzionerà\_ se aggiorni la versione Express nelle sue dipendenze. Questo articolo comprende: @@ -28,7 +28,8 @@ Nel documento Express 4 sono stati apportati diversi cambiamenti significativi:
          • Change to Express core and middleware system. Le dipendenze da - Connect e built-in middleware sono state rimosse, quindi è necessario aggiungere middleware da soli. + Connect e built-in middleware sono state rimosse, quindi è necessario aggiungere middleware da + soli.
          • Modifiche al sistema di routing. @@ -40,8 +41,8 @@ Nel documento Express 4 sono stati apportati diversi cambiamenti significativi: Cfr. anche: -* [Nuove funzionalità in 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) -* [Migrazione da 3.x a 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) +- [Nuove funzionalità in 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +- [Migrazione da 3.x a 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) ### Modifiche al sistema Express core e middleware @@ -214,8 +215,8 @@ il middleware `router`. Il modo in cui definisci i percorsi non è cambiato, ma il sistema di routing ha due nuove funzionalità per aiutare a organizzare i tuoi percorsi: -* Un nuovo metodo, `app.route()`, per creare i gestori di rotte per un percorso tracciato. -* Una nuova classe, `express.Router`, per creare percorsi modulari montabili. +- Un nuovo metodo, `app.route()`, per creare i gestori di rotte per un percorso tracciato. +- Una nuova classe, `express.Router`, per creare percorsi modulari montabili. #### `app.route()` metodo @@ -229,14 +230,14 @@ Ecco un esempio di router incatenati che sono definiti utilizzando la funzione ` app .route('/book') .get((req, res) => { - res. end('Ottieni un libro casuale'); + res.end('Ottieni un libro casuale'); }) - . ost((req, res) => { + .ost((req, res) => { res.send('Add a book'); }) - . ut((req, res) => { + .ut((req, res) => { res.send('Aggiorna il libro'); -}); + }); ``` #### Classe `express.Router` @@ -298,13 +299,16 @@ La seguente tabella elenca altre modifiche di piccole dimensioni ma importanti i Node.js - Express 4 richiede Node.js 0.10.x o versioni successive e ha abbandonato il supporto per Node.js 0.8.x. + + Express 4 richiede Node.js 0.10.x o versioni successive e ha abbandonato il supporto per + Node.js 0.8.x. + `http.createServer()` - Il modulo `http` non è più necessario, a meno che non sia necessario lavorare direttamente con esso - (socket.io/SPDY/HTTPS). L'app può essere avviata utilizzando la funzione `app.listen()`. + Il modulo `http` non è più necessario, a meno che non sia necessario lavorare direttamente con + esso (socket.io/SPDY/HTTPS). L'app può essere avviata utilizzando la funzione `app.listen()`. @@ -317,7 +321,8 @@ La seguente tabella elenca altre modifiche di piccole dimensioni ma importanti i `json spaces` - La proprietà dell'applicazione `json spaces` è disabilitata per impostazione predefinita in Express 4. + La proprietà dell'applicazione `json spaces` è disabilitata per impostazione predefinita in + Express 4. @@ -358,8 +363,8 @@ La seguente tabella elenca altre modifiche di piccole dimensioni ma importanti i `res.setHeader('Set-Cookie', val)` - La funzionalità è ora limitata all'impostazione del valore di base dei cookie. Usa `res.cookie()` per le funzionalità - aggiunte. + La funzionalità è ora limitata all'impostazione del valore di base dei cookie. Usa + `res.cookie()` per le funzionalità aggiunte. @@ -595,9 +600,9 @@ Express 4. Le opzioni di comando e l'uso restano in gran parte uguali, con le seguenti eccezioni: -* Rimosso l'opzione `--sessions`. -* Rimosso l'opzione `--jshtml`. -* Aggiunta l'opzione `--hogan` per supportare [Hogan.js](http://twitter.github.io/hogan.js/). +- Rimosso l'opzione `--sessions`. +- Rimosso l'opzione `--jshtml`. +- Aggiunta l'opzione `--hogan` per supportare [Hogan.js](http://twitter.github.io/hogan.js/). ### Esempio diff --git a/src/content/pages/it/guide/migrating-5.mdx b/src/content/pages/it/guide/migrating-5.mdx index 8dc4a60c8e..3dda509552 100644 --- a/src/content/pages/it/guide/migrating-5.mdx +++ b/src/content/pages/it/guide/migrating-5.mdx @@ -166,7 +166,7 @@ app.del('/user/:id', (req, res) => { }); // v5 -app. elete('/user/:id', (req, res) => { +app.elete('/user/:id', (req, res) => { res.send(`DELETE /user/${req.params.id}`); }); ``` @@ -198,14 +198,14 @@ npx codemod@latest @expressjs/pluralize-method-names // v4 app.all('/', (req, res) => { req.acceptsCharset('utf-8'); - req. cceptsEncoding('br'); + req.cceptsEncoding('br'); req.acceptsLanguage('en'); // ... }); // v5 -app. ll('/', (req, res) => { +app.ll('/', (req, res) => { req.acceptsCharsets('utf-8'); req.acceptsEncodings('br'); req.acceptsLanguages('en'); @@ -237,7 +237,7 @@ npx codemod@latest @expressjs/explicit-request-params // v4 app.post('/user', (req, res) => { const id = req.param('id'); - const body = req. aram('body'); + const body = req.aram('body'); const query = req.param('query'); // ... @@ -245,7 +245,7 @@ app.post('/user', (req, res) => { // v5 app.post('/user', (req, res) => { - const id = req.params. d; + const id = req.params.d; const body = req.body; const query = req.query; @@ -273,7 +273,7 @@ app.post('/user', (req, res) => { }); // v5 -app. ost('/user', (req, res) => { +app.ost('/user', (req, res) => { res.status(201).json({ name: 'Ruben' }); }); ``` @@ -298,7 +298,7 @@ app.post('/user', (req, res) => { }); // v5 -app. ost('/user', (req, res) => { +app.ost('/user', (req, res) => { res.status(201).jsonp({ name: 'Ruben' }); }); ``` @@ -323,7 +323,7 @@ app.get('/user', (req, res) => { }); // v5 -app. et('/user', (req, res) => { +app.et('/user', (req, res) => { res.redirect(301, '/users'); }); ``` @@ -373,7 +373,7 @@ app.get('/user', (req, res) => { }); // v5 -app. et('/user', (req, res) => { +app.et('/user', (req, res) => { res.status(200).send({ name: 'Ruben' }); }); ``` @@ -410,12 +410,12 @@ La funzione `res.sendfile()` è stata sostituita da una versione a cassa in camm **Nota:** In Express 5, `res. endFile()` utilizza il pacchetto `mime-types` per il rilevamento del tipo MIME, che restituisce diversi valori di Content-Type rispetto a Express 4 per diversi tipi di file comuni: -* File JavaScript (.js): ora "text/javascript" invece di "application/javascript" -* File JSON (.json): ora "application/json" invece di "text/json" -* File CSS (.css): ora "text/css" invece di "text/plain" -* File XML (.xml): ora "application/xml" invece di "text/xml" -* File dei caratteri (.woff): ora "font/woff" invece di "application/font-woff" -* File SVG (.svg): ora "image/svg+xml" invece di "application/svg+xml" +- File JavaScript (.js): ora "text/javascript" invece di "application/javascript" +- File JSON (.json): ora "application/json" invece di "text/json" +- File CSS (.css): ora "text/css" invece di "text/plain" +- File XML (.xml): ora "application/xml" invece di "text/xml" +- File dei caratteri (.woff): ora "font/woff" invece di "application/font-woff" +- File SVG (.svg): ora "image/svg+xml" invece di "application/svg+xml" È possibile sostituire le firme deprecate con il seguente comando: @@ -449,12 +449,12 @@ Usa il pacchetto [`mime-types`](https://github.com/jshttp/mime-types) per lavora **Importante:** Questa modifica influisce non solo sull'uso diretto di `express.static.mime` ma anche su altri metodi Express che si basano sul rilevamento del tipo MIME, come `res.sendFile()`. I seguenti tipi di MIME sono cambiati da Express 4: -* File JavaScript (.js): ora servito come "text/javascript" invece di "application/javascript" -* File JSON (.json): ora servito come "application/json" invece di "text/json" -* File CSS (.css): ora servito come "text/css" invece di "text/plain" -* File HTML (): ora servito come "text/html; charset=utf-8" invece di "text/html" -* File XML (.xml): ora servito come "application/xml" invece di "text/xml" -* File di carattere (.woff): ora servito come "font/woff" invece di "application/font-woff" +- File JavaScript (.js): ora servito come "text/javascript" invece di "application/javascript" +- File JSON (.json): ora servito come "application/json" invece di "text/json" +- File CSS (.css): ora servito come "text/css" invece di "text/plain" +- File HTML (): ora servito come "text/html; charset=utf-8" invece di "text/html" +- File XML (.xml): ora servito come "application/xml" invece di "text/xml" +- File di carattere (.woff): ora servito come "font/woff" invece di "application/font-woff" ```js // v4 @@ -490,7 +490,7 @@ DEBUG=express:*,router,router:* node index.js Il percorso percorso corrispondente alla sintassi è quando una stringa viene fornita come primo parametro alle API `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, e `router.use()`. Sono state apportate le seguenti modifiche a come la stringa del percorso è abbinata a una richiesta in ingresso: -* Il carattere jolly `*` deve avere un nome, corrispondente al comportamento dei parametri `:`, usa `/*splat` invece di `/*` +- Il carattere jolly `*` deve avere un nome, corrispondente al comportamento dei parametri `:`, usa `/*splat` invece di `/*` ```js // v4 @@ -499,7 +499,7 @@ app.get('/*', async (req, res) => { }); // v5 -app. et('/*splat', async (req, res) => { +app.et('/*splat', async (req, res) => { res.send('ok'); }); ``` @@ -516,7 +516,7 @@ app.get('/{*splat}', async (req, res) => { -* Il carattere opzionale `?` non è più supportato, utilizza invece le graffe. +- Il carattere opzionale `?` non è più supportato, utilizza invece le graffe. ```js // v4 @@ -525,12 +525,12 @@ app.get('/:file.:ext?', async (req, res) => { }); // v5 -app. et('/:file{.:ext}', async (req, res) => { +app.et('/:file{.:ext}', async (req, res) => { res.send('ok'); }); ``` -* I caratteri Regexp non sono supportati. Per esempio: +- I caratteri Regexp non sono supportati. Per esempio: ```js app.get('/[discussion page]/:slug', async (req, res) => { @@ -546,8 +546,8 @@ app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { }); ``` -* Alcuni caratteri sono stati riservati per evitare confusione durante l'aggiornamento (`()[]?+!`), usa `\` per sfuggire a loro. -* I nomi dei parametri ora supportano identificativi JavaScript validi, o citati come `:"this"`. +- Alcuni caratteri sono stati riservati per evitare confusione durante l'aggiornamento (`()[]?+!`), usa `\` per sfuggire a loro. +- I nomi dei parametri ora supportano identificativi JavaScript validi, o citati come `:"this"`. ### Promesse respinte gestite da middleware e gestori @@ -619,7 +619,7 @@ I caratteri jolly (ad esempio, `/*splat`) catturano i segmenti di percorso come ```js app.get('/*splat', (req, res) => { // GET /foo/bar - console.dir(req. arams); + console.dir(req.arams); // => [Object: null prototype] { splat: [ 'foo', 'bar' ] } }); ``` diff --git a/src/content/pages/it/resources/glossary.mdx b/src/content/pages/it/resources/glossary.mdx index f28ec021a5..794a8f4393 100644 --- a/src/content/pages/it/resources/glossary.mdx +++ b/src/content/pages/it/resources/glossary.mdx @@ -25,9 +25,9 @@ Una libreria di supporto multi-piattaforma che si concentra su I/O asincrono svi Una funzione che viene invocata dallo strato di routing Express prima del gestore finale della richiesta, e si siede così al centro tra una richiesta grezza e il percorso finale previsto. Alcuni punti di fine terminologia intorno al middleware: -* `var foo = require('middleware')` si chiama *requiring* o *using* un modulo Node.js. Quindi la dichiarazione `var mw = foo()` restituisce tipicamente il middleware. -* `app.use(mw)` si chiama *aggiungendo il middleware allo stack globale di elaborazione*. -* `app.get('/foo', mw, function (req, res) { ... })` si chiama _aggiungendo il middleware allo stack di elaborazione "GET /foo" . +- `var foo = require('middleware')` si chiama _requiring_ o _using_ un modulo Node.js. Quindi la dichiarazione `var mw = foo()` restituisce tipicamente il middleware. +- `app.use(mw)` si chiama _aggiungendo il middleware allo stack globale di elaborazione_. +- `app.get('/foo', mw, function (req, res) { ... })` si chiama \_aggiungendo il middleware allo stack di elaborazione "GET /foo" . ### Node.js diff --git a/src/content/pages/it/resources/utils.md b/src/content/pages/it/resources/utils.md index 4069421b0f..b017cc6caf 100644 --- a/src/content/pages/it/resources/utils.md +++ b/src/content/pages/it/resources/utils.md @@ -8,15 +8,15 @@ description: Scopri i moduli di utilità relativi a Express.js e Node.js, inclus L'organizzazione [pillarjs](https://github.com/pillarjs) GitHub contiene una serie di moduli per funzioni di utilità che possono essere generalmente utili. -| Moduli di utilità | Descrizione | -| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Moduli di utilità | Descrizione | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | [cookies](https://www.npmjs.com/package/cookies) | Ottieni e imposta i cookie HTTP(S) che possono essere firmati per evitare manomissioni, utilizzando Keygrip. Può essere utilizzato con la libreria HTTP Node.js o come middleware Express. | -| [csrf](https://www.npmjs.com/package/csrf) | Contiene la logica dietro la creazione e la verifica del token CSRF. Usa questo modulo per creare middleware CSRF personalizzato. | -| [finalhandler](https://www.npmjs.com/package/finalhandler) | Funzione di invocare come passo finale per rispondere alla richiesta HTTP. | -| [parseurl](https://www.npmjs.com/package/parseurl) | Analizza un URL con la cache. | -| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Trasforma una stringa di percorso in stile Express, come \`\`/user/:name\` in un'espressione regolare. | -| [resolve-path](https://www.npmjs.com/package/resolve-path) | Risolve un percorso relativo contro un percorso radice con convalida. | -| [router](https://www.npmjs.com/package/router) | Semplice router in stile middleware. | -| [send](https://www.npmjs.com/package/send) | Libreria per lo streaming di file come risposta HTTP, con supporto per risposte parziali (intervalli), negoziazione condizionale-GET ed eventi granulari. | +| [csrf](https://www.npmjs.com/package/csrf) | Contiene la logica dietro la creazione e la verifica del token CSRF. Usa questo modulo per creare middleware CSRF personalizzato. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Funzione di invocare come passo finale per rispondere alla richiesta HTTP. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Analizza un URL con la cache. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Trasforma una stringa di percorso in stile Express, come \`\`/user/:name\` in un'espressione regolare. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Risolve un percorso relativo contro un percorso radice con convalida. | +| [router](https://www.npmjs.com/package/router) | Semplice router in stile middleware. | +| [send](https://www.npmjs.com/package/send) | Libreria per lo streaming di file come risposta HTTP, con supporto per risposte parziali (intervalli), negoziazione condizionale-GET ed eventi granulari. | Per ulteriori moduli correlati all'HTTP di basso livello, vedere [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/it/support.md b/src/content/pages/it/support.md index caec4f1d23..2a10bed63e 100644 --- a/src/content/pages/it/support.md +++ b/src/content/pages/it/support.md @@ -7,14 +7,14 @@ description: Trova informazioni sul programma di supporto per le diverse version Versioni che sono EOL (end-of-life) _may_ ricevere aggiornamenti per le vulnerabilità di sicurezza critiche, ma il team Express non offre alcuna garanzia e non prevede di affrontare o risolvere i problemi riscontrati. -| Versione Maggiore | Versione Minima Node.js | Data Inizio Supporto | Data Di Fine Supporto | -| ------------------------------------------- | --------------------------------------- | -------------------- | --------------------- | -| [**v5.x**](/en/5x/api) | 18 | Settembre 2024 | **in corso** | -| [**v4.x**](/en/4x/api) | 0.10.0 | Aprile 2014 | **in corso** | -| [**v3.x**](/en/3x/api) | 0.8.0 | Ottobre 2012 | Luglio 2015 | -| [**v2.x**](/2x/) | 0.4.1 | Marzo 2011 | Luglio 2012 | -| **v1.x** | 0.2.0 | Dicembre 2010 | Marzo 2011 | -| **v0.14.x** | 0.1.98 | Dicembre 2010 | Dicembre 2010 | +| Versione Maggiore | Versione Minima Node.js | Data Inizio Supporto | Data Di Fine Supporto | +| ---------------------- | ----------------------- | -------------------- | --------------------- | +| [**v5.x**](/en/5x/api) | 18 | Settembre 2024 | **in corso** | +| [**v4.x**](/en/4x/api) | 0.10.0 | Aprile 2014 | **in corso** | +| [**v3.x**](/en/3x/api) | 0.8.0 | Ottobre 2012 | Luglio 2015 | +| [**v2.x**](/2x/) | 0.4.1 | Marzo 2011 | Luglio 2012 | +| **v1.x** | 0.2.0 | Dicembre 2010 | Marzo 2011 | +| **v0.14.x** | 0.1.98 | Dicembre 2010 | Dicembre 2010 | ## Opzioni Di Supporto Commerciale diff --git a/src/content/pages/ja/advanced/best-practice-performance.md b/src/content/pages/ja/advanced/best-practice-performance.md index 8ec6ee7e87..ee1b15f619 100644 --- a/src/content/pages/ja/advanced/best-practice-performance.md +++ b/src/content/pages/ja/advanced/best-practice-performance.md @@ -132,7 +132,7 @@ app.use(async (req, res, next) => { #### 何をしないか -`unchaughtException`をリッスンするのは_しないでください。 イベントループに戻るまで例外が発生した場合に発生します。 `uncaughtException` に対してイベントリスナーを追加すると、例外に遭遇するプロセスのデフォルトの動作が変更されます。 例外にもかかわらずこのプロセスは続けられます これはアプリがクラッシュするのを防ぐ良い方法に思えるかもしれません。 しかし、未取得の例外が危険な方法であり、推奨されていない場合、アプリを実行し続けます。 プロセスの状態は信頼できず予測不能になるからです +`unchaughtException`をリッスンするのは\_しないでください。 イベントループに戻るまで例外が発生した場合に発生します。 `uncaughtException` に対してイベントリスナーを追加すると、例外に遭遇するプロセスのデフォルトの動作が変更されます。 例外にもかかわらずこのプロセスは続けられます これはアプリがクラッシュするのを防ぐ良い方法に思えるかもしれません。 しかし、未取得の例外が危険な方法であり、推奨されていない場合、アプリを実行し続けます。 プロセスの状態は信頼できず予測不能になるからです さらに、 `uncaughtException` を使用すると、公式に [crude](https://nodejs.org/api/process#process_event_uncaughtexception) として認識されます。 ですから、 `unchaughtException` を聴くのは悪い考えです。 このため、複数のプロセスやスーパーバイザのようなものをお勧めします。クラッシュと再起動は、多くの場合、エラーから回復する最も信頼性の高い方法です。 @@ -208,7 +208,7 @@ Express アプリで init システムを使用するには、次の 2 つの方 SystemdはLinuxシステムとサービスマネージャーです。 ほとんどの主要な Linux ディストリビューションでは、systemd をデフォルトの init システムとして採用しています。 -systemd サービスの設定ファイルは _unit file_と呼ばれ、ファイル名は `.service` で終わります。 Nodeアプリケーションを直接管理するためのユニットファイルの例を示します。 ``で囲まれたシステムとアプリの値を置き換えます。 +systemd サービスの設定ファイルは *unit file*と呼ばれ、ファイル名は `.service` で終わります。 Nodeアプリケーションを直接管理するためのユニットファイルの例を示します。 ``で囲まれたシステムとアプリの値を置き換えます。 ```sh [Unit] @@ -258,7 +258,7 @@ systemd の詳細については、[systemd reference (man page)](http://www.fre #### PM2の使用 -PM2を使用してアプリケーションをデプロイする場合は、_without_アプリケーションコードを変更するクラスタリングを利用できます。 [application is stateless](https://pm2.keymetrics.io/docs/usage/specifics/#stateless-apps) を最初に確認してください。 つまり、プロセスにローカルデータは保存されません(セッション、WebSocket接続など)。 +PM2を使用してアプリケーションをデプロイする場合は、*without*アプリケーションコードを変更するクラスタリングを利用できます。 [application is stateless](https://pm2.keymetrics.io/docs/usage/specifics/#stateless-apps) を最初に確認してください。 つまり、プロセスにローカルデータは保存されません(セッション、WebSocket接続など)。 PM2を使用してアプリケーションを実行する場合、**クラスタモード**を有効にして、選択した複数のインスタンスを使用してクラスタで実行できます。 例えば、マシン上の利用可能なCPU数と一致するなど。 `pm2`コマンドラインツールを使って、クラスタ内のプロセス数を手動で変更できます。 @@ -296,7 +296,7 @@ For more information on clustering with PM2, see [Cluster Mode](https://pm2.keym ロードバランサは通常、複数のアプリケーションインスタンスとサーバーとの間でトラフィックをオーケストレーションするリバースプロキシです。 アプリのロードバランサーは、 [Nginx](https://nginx.org/en/docs/http/load_balancing) または [HAProxy](https://www.digitalocean.com/community/tutorials/an-introduction-to-haproxy-and-load-balancing-concepts) を使用して簡単に設定できます。 -ロードバランシングでは、特定のセッション ID に関連付けられているリクエストがそれらを起動したプロセスに接続されていることを確認する必要があります。 これは_session affinity_または_sticky sessions_として知られています。 そして、セッションデータにRedisなどのデータストアを使用するために上記の提案によって対処される場合があります(アプリケーションによって異なります)。 For a discussion, see [Using multiple nodes](https://socket.io/docs/v4/using-multiple-nodes/). +ロードバランシングでは、特定のセッション ID に関連付けられているリクエストがそれらを起動したプロセスに接続されていることを確認する必要があります。 これは*session affinity*または*sticky sessions*として知られています。 そして、セッションデータにRedisなどのデータストアを使用するために上記の提案によって対処される場合があります(アプリケーションによって異なります)。 For a discussion, see [Using multiple nodes](https://socket.io/docs/v4/using-multiple-nodes/). ### リバースプロキシを使用 diff --git a/src/content/pages/ja/advanced/best-practice-security.mdx b/src/content/pages/ja/advanced/best-practice-security.mdx index 593c000bf5..eb85967ae7 100644 --- a/src/content/pages/ja/advanced/best-practice-security.mdx +++ b/src/content/pages/ja/advanced/best-practice-security.mdx @@ -5,7 +5,7 @@ description: 運用中のExpressアプリのセキュリティベストプラク import Alert from '@components/primitives/Alert/Alert.astro'; -*"production"* という用語は、アプリケーションや API がエンドユーザーや消費者に一般的に提供されるソフトウェアのライフサイクルにおける段階を指します。 対照的に、_"development"_段階では、コードを積極的に書いたりテストしたりしており、アプリケーションは外部からのアクセスに開かれていません。 対応するシステム環境はそれぞれ *production* と *development* と呼ばれています。 +_"production"_ という用語は、アプリケーションや API がエンドユーザーや消費者に一般的に提供されるソフトウェアのライフサイクルにおける段階を指します。 対照的に、*"development"*段階では、コードを積極的に書いたりテストしたりしており、アプリケーションは外部からのアクセスに開かれていません。 対応するシステム環境はそれぞれ _production_ と _development_ と呼ばれています。 開発環境と生産環境は通常、異なる設定であり、非常に異なる要件を持っています。 開発で問題のあるものは、生産では受け入れられないかもしれません。 たとえば、開発環境では、デバッグ用のエラーの詳細なロギングを行うことができます。 同じ行動が本番環境ではセキュリティ上の懸念になることがあります 開発では拡張性、信頼性、パフォーマンスを心配する必要はありませんが、それらの懸念は生産において重要になります。 @@ -18,21 +18,21 @@ Express でセキュリティ上の脆弱性を発見したと思われる場合 実稼働中の Express アプリケーションのセキュリティのベスト プラクティスは以下のとおりです。 -* [プロダクションのベストプラクティス: セキュリティ] (#production-best-practices-security) - * [Overview](#overview) - * [Expressの非推奨バージョンや脆弱バージョンを使用しないでください](#dont-use-deprecated-or-vulnerable-versions-of-express) - * [Use TLS](#use-tls) - * [Do not trust user input](#do-not-trust-user-input) - * [Prevent open redirects](#prevent-open-redirects) - * [Use Helmet](#use-helmet) - * [Reduce fingerprinting](#reduce-fingerprinting) - * [Use cookies securely](#use-cookies-securely) - * [Don't use the default session cookie name](#dont-use-the-default-session-cookie-name) - * [Set cookie security options](#set-cookie-security-options) - * [Prevent brute-force attacks against authorization](#prevent-brute-force-attacks-against-authorization) - * [Ensure your dependencies are secure](#ensure-your-dependencies-are-secure) - * [Avoid other known vulnerabilities](#avoid-other-known-vulnerabilities) - * [Additional considerations](#additional-considerations) +- [プロダクションのベストプラクティス: セキュリティ] (#production-best-practices-security) + - [Overview](#overview) + - [Expressの非推奨バージョンや脆弱バージョンを使用しないでください](#dont-use-deprecated-or-vulnerable-versions-of-express) + - [Use TLS](#use-tls) + - [Do not trust user input](#do-not-trust-user-input) + - [Prevent open redirects](#prevent-open-redirects) + - [Use Helmet](#use-helmet) + - [Reduce fingerprinting](#reduce-fingerprinting) + - [Use cookies securely](#use-cookies-securely) + - [Don't use the default session cookie name](#dont-use-the-default-session-cookie-name) + - [Set cookie security options](#set-cookie-security-options) + - [Prevent brute-force attacks against authorization](#prevent-brute-force-attacks-against-authorization) + - [Ensure your dependencies are secure](#ensure-your-dependencies-are-secure) + - [Avoid other known vulnerabilities](#avoid-other-known-vulnerabilities) + - [Additional considerations](#additional-considerations) ## 非推奨または脆弱なバージョンの Express を使用しない @@ -44,7 +44,7 @@ Also ensure you are not using any of the vulnerable Express versions listed on t 機密データを扱ったり転送したりする場合は、[Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) を使用して接続とデータを保護します。 この技術は、クライアントからサーバーに送信される前にデータを暗号化し、一般的な(そして簡単な)ハッキングを防ぎます。 Ajax と POST リクエストは目に見えて明らかではなく、ブラウザーでは「非表示」に見えるかもしれません。 彼らのネットワークトラフィックは、[パケットスニッフィング](https://en.wikipedia.org/wiki/Packet_analyzer)と[man-in-the-middle攻撃](https://en.wikipedia.org/wiki/Man-in-the-middle_attack)に対して脆弱です。 -You may be familiar with Secure Socket Layer (SSL) encryption. [TLS は、単に SSLの次の進行である](\)。 言い換えれば、以前SSLを使用していた場合は、TLSへのアップグレードを検討してください。 一般的に、Nginx は TLS を扱うことをお勧めします。 Nginx (および他のサーバ) で TLS を設定するための参考情報については、[推奨サーバー構成 (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations)を参照してください。 +You may be familiar with Secure Socket Layer (SSL) encryption. [TLS は、単に SSLの次の進行である](<%3Chttps://msdn.microsoft.com/en-us/library/windows/desktop/aa380515(v=vs.85).aspx%3E>)。 言い換えれば、以前SSLを使用していた場合は、TLSへのアップグレードを検討してください。 一般的に、Nginx は TLS を扱うことをお勧めします。 Nginx (および他のサーバ) で TLS を設定するための参考情報については、[推奨サーバー構成 (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations)を参照してください。 Also, a handy tool to get a free TLS certificate is [Let's Encrypt](https://letsencrypt.org/about/), a free, automated, and open certificate authority (CA) provided by the [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). @@ -55,7 +55,7 @@ Webアプリケーションの場合、最も重要なセキュリティ要件 ### 開いているリダイレクトを防止 -潜在的に危険なユーザー入力の例は *open redirect* です。 ここで、アプリケーションはユーザー入力としてURLを受け入れます (多くの場合、URLクエリでは、例えば`? rl=https://example. om`) `res.redirect` を使用して、 `location` ヘッダーを設定し、 +潜在的に危険なユーザー入力の例は _open redirect_ です。 ここで、アプリケーションはユーザー入力としてURLを受け入れます (多くの場合、URLクエリでは、例えば`? rl=https://example. om`) `res.redirect` を使用して、 `location` ヘッダーを設定し、 は 3xx ステータスを返します。 アプリケーションは、フィッシングサイトなどの悪意のあるリンクにユーザーを送信しないように、着信URLへのリダイレクトをサポートしていることを検証する必要があります。 他のリスクの中でもね @@ -81,19 +81,19 @@ app.use((req, res) => { Helmet は、セキュリティ関連の HTTP レスポンスヘッダーを設定するミドルウェア機能です。 ヘルメットは、デフォルトで次のヘッダーを設定します。 -* `Content-Security-Policy`: 多くの攻撃を軽減するためにあなたのページで何が起こるかを許可する強力なリスト -* `Cross-Origin-Opener-Policy`: あなたのページを分離するのに役立ちます -* `Cross-Origin-Resource-Policy`: クロスオリジンからリソースを読み込むことをブロックします -* `Origin-Agent-Cluster`: プロセスの分離を元ベースに変更します -* `Referrer-Policy`: [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) ヘッダーを制御します -* `Strict-Transport-Security`: HTTPSを好むようブラウザーに教える -* `X-Content-Type-Options`: 回避 [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) -* `X-DNS-Prefetch-Control`: DNS プリフェッチを制御します -* `X-Download-Options`: 強制的にダウンロードを保存します (Internet Explorerのみ) -* `X-Frame-Options`: [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) 攻撃を軽減する従来のヘッダー -* `X-Permitted-Cross-Domain-Policies`: Acrobat など、Adobe 製品のクロスドメイン動作を制御します -* `X-Powered-By`: Webサーバーに関する情報。 簡単な攻撃で使用できるため削除されました -* `X-XSS-Protection`: [XSS アタック]（https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting）を軽減しようとするレガシーヘッダーが悪化するため、ヘルメットは無効にします +- `Content-Security-Policy`: 多くの攻撃を軽減するためにあなたのページで何が起こるかを許可する強力なリスト +- `Cross-Origin-Opener-Policy`: あなたのページを分離するのに役立ちます +- `Cross-Origin-Resource-Policy`: クロスオリジンからリソースを読み込むことをブロックします +- `Origin-Agent-Cluster`: プロセスの分離を元ベースに変更します +- `Referrer-Policy`: [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) ヘッダーを制御します +- `Strict-Transport-Security`: HTTPSを好むようブラウザーに教える +- `X-Content-Type-Options`: 回避 [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +- `X-DNS-Prefetch-Control`: DNS プリフェッチを制御します +- `X-Download-Options`: 強制的にダウンロードを保存します (Internet Explorerのみ) +- `X-Frame-Options`: [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) 攻撃を軽減する従来のヘッダー +- `X-Permitted-Cross-Domain-Policies`: Acrobat など、Adobe 製品のクロスドメイン動作を制御します +- `X-Powered-By`: Webサーバーに関する情報。 簡単な攻撃で使用できるため削除されました +- `X-XSS-Protection`: [XSS アタック]（https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting）を軽減しようとするレガシーヘッダーが悪化するため、ヘルメットは無効にします 各ヘッダーは、設定または無効にできます。 詳細については、[its documentation website][helmet] をご覧ください。 @@ -164,8 +164,8 @@ app.use((err, req, res, next) => { 2つの主なミドルウェアのセッションモジュールがあります。 -* `express.session`ミドルウェアをExpress 3.xに置き換える[express-session](https://www.npmjs.com/package/express-session) -* `express.cookieSession` ミドルウェアをExpress 3.xに置き換える[cookie-session](https://www.npmjs.com/package/cookie-session) +- `express.session`ミドルウェアをExpress 3.xに置き換える[express-session](https://www.npmjs.com/package/express-session) +- `express.cookieSession` ミドルウェアをExpress 3.xに置き換える[cookie-session](https://www.npmjs.com/package/cookie-session) これらの2つのモジュールの主な違いは、クッキーセッションデータの保存方法です。 [express-session](https://www.npmjs.com/package/express-session) ミドルウェアは、セッションデータをサーバー上に保存します。セッションIDは、セッションデータではなく、クッキー自体にのみ保存します。 デフォルトでは、インメモリストレージを使用し、本番環境用に設計されていません。 本番環境では、スケーラブルな session-store を設定する必要があります。[compatible session store](https://github.com/expressjs/session#compatible-session-stores) のリストを参照してください。 @@ -192,11 +192,11 @@ app.use( セキュリティを強化するために、次のクッキーオプションを設定します。 -* `secure` - HTTPS経由でのみCookieを送信できるようにします。 -* `httpOnly` - CookieがクライアントJavaScriptではなくHTTP(S)上でのみ送信されることを保証し、クロスサイトスクリプティング攻撃から保護します。 -* `domain` - Cookie のドメインを示します。URL がリクエストされているサーバーのドメインと比較するために使用します。 一致する場合は、次にパス属性を確認します。 -* `path` - クッキーのパスを示します。リクエストパスと比較するために使用します。 これとドメインが一致した場合は、リクエストにクッキーを送信します。 -* `expires` - 永続的クッキーの有効期限を設定するために使用します。 +- `secure` - HTTPS経由でのみCookieを送信できるようにします。 +- `httpOnly` - CookieがクライアントJavaScriptではなくHTTP(S)上でのみ送信されることを保証し、クロスサイトスクリプティング攻撃から保護します。 +- `domain` - Cookie のドメインを示します。URL がリクエストされているサーバーのドメインと比較するために使用します。 一致する場合は、次にパス属性を確認します。 +- `path` - クッキーのパスを示します。リクエストパスと比較するために使用します。 これとドメインが一致した場合は、リクエストにクッキーを送信します。 +- `expires` - 永続的クッキーの有効期限を設定するために使用します。 [cookie-session](https://www.npmjs.com/package/cookie-session) ミドルウェアを使用した例を以下に示します。 @@ -267,10 +267,10 @@ Finally, Express apps—like any other web apps—can be vulnerable to a 優れた [Node.js セキュリティ チェックリスト](https://blog.risingstack.com/node-js-security-checklist/) からのさらなる推奨事項をいくつか紹介します。 これらの推奨事項の詳細については、そのブログ記事を参照してください。 -* クロスサイト・スクリプティング(XSS)やコマンドインジェクション攻撃から保護するため、常にユーザー入力をフィルタリングしてサニタイズします。 -* パラメータ化されたクエリまたは準備された文を使用してSQLインジェクション攻撃を防御します。 -* アプリケーションのSQLインジェクションの脆弱性を検出するには、オープンソースの [sqlmap](http://sqlmap.org/)ツールを使用してください。 -* SSL暗号の設定をテストするには、 [nmap](https://nmap.org/) と [sslyze](https://github.com/nabla-c0d3/sslyze) ツールを使用します。 キー、再ネゴシエーション、および証明書の有効性。 -* [safe-regex](https://www.npmjs.com/package/safe-regex) を使用して、正規表現が [正規表現 サービス妨害](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) 攻撃の影響を受けないようにしましょう。 +- クロスサイト・スクリプティング(XSS)やコマンドインジェクション攻撃から保護するため、常にユーザー入力をフィルタリングしてサニタイズします。 +- パラメータ化されたクエリまたは準備された文を使用してSQLインジェクション攻撃を防御します。 +- アプリケーションのSQLインジェクションの脆弱性を検出するには、オープンソースの [sqlmap](http://sqlmap.org/)ツールを使用してください。 +- SSL暗号の設定をテストするには、 [nmap](https://nmap.org/) と [sslyze](https://github.com/nabla-c0d3/sslyze) ツールを使用します。 キー、再ネゴシエーション、および証明書の有効性。 +- [safe-regex](https://www.npmjs.com/package/safe-regex) を使用して、正規表現が [正規表現 サービス妨害](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) 攻撃の影響を受けないようにしましょう。 [helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/ja/advanced/security-updates.mdx b/src/content/pages/ja/advanced/security-updates.mdx index adb45bfb10..7af30ba04f 100644 --- a/src/content/pages/ja/advanced/security-updates.mdx +++ b/src/content/pages/ja/advanced/security-updates.mdx @@ -24,42 +24,42 @@ Express でセキュリティ上の脆弱性を発見したと思われる場合 ## 4.x -* 4.21.2 - * 依存関係の `path-to-regexp` が [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w) に対応するように更新されました。 -* 4.21.1 - * 依存関係の `cookie` が [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x) アドレスに更新されました。`res.cookie` を使用すると、アプリケーションに影響する可能性があります。 -* 4.20.0 - * `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796))におけるXSSの脆弱性の修正。 - * 依存関係の `serve-static` が [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p) に更新されました。 - * 依存関係の `send` が [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg) に更新されました。 - * 依存関係の `path-to-regexp` が [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j) に対応するように更新されました。 - * 依存関係の `body-parser` が [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7) を追加するように更新されました。これはURLエンコンデーションが有効になっている場合、アプリケーションに影響する可能性があります。 -* 4.19.0, 4.19.1 - * `res.location` と `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)のオープンリダイレクトの脆弱性を修正しました。 -* 4.17.3 - * 依存関係の `qs` が [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp) に更新されました。 `req.query`、`req.body`、`req.param`という以下のAPIを使用すると、アプリケーションに影響を与える可能性があります。 -* 4.16.0 - * 依存関係の `forwarded` が [vulnerability](https://npmjs.com/advisories/527) に更新されました。 以下の API が使用されている場合、アプリケーションに影響を与える可能性があります: `req.host` 、 `req.hostname` 、 `req.ips` 、 `req.protocol` 。 - * 依存関係の `mime` が [vulnerability](https://npmjs.com/advisories/535) 宛先に更新されましたが、この問題は Express には影響しません。 - * 依存関係の `send` が更新され、[Node.js 8.5.0 脆弱性](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/)に対する保護が提供されました。 これは、Express が特定の Node.js バージョン 8.5.0 で実行されることにのみ影響します。 -* 4.15.5 - * 依存関係の `debug` が [vulnerability](https://snyk.io/vuln/npm:debug:20170905) アドレスに更新されましたが、この問題は Express には影響しません。 - * 依存関係の `fresh` が [vulnerability](https://npmjs.com/advisories/526) に更新されました。 `express.static` 、 `req.fresh` 、 `res.json` 、 `res.json` 、 `res.send` 、 `res.send` 、 `res.sendFile` 、 `res.sendFile` 、 `res.sendStatus` などのAPIが使用されると、アプリケーションに影響します。 -* 4.15.3 - * 依存関係の `ms` が [vulnerability](https://snyk.io/vuln/npm:ms:20170412) に更新されました。 信頼されていない文字列が次の API で `maxAge` オプションに渡されると、アプリケーションに影響を与える可能性があります。`express.static` 、 `res.sendfile` 、 `res.sendFile` です。 -* 4.15.2 - * 依存関係`qs`が [vulnerability]（https://snyk.io/vuln/npm:qs:20170213）アドレスに更新されましたが、この問題はExpressには影響しません。 4.15.2 へのアップデートは良い方法ですが、脆弱性に対処する必要はありません。 -* 4.11.1 - * `express.static`、`res.sendfile`、`res.sendFile`におけるルートパス開示の脆弱性を修正しました。 -* 4.10.7 - * `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)のオープンリダイレクトの脆弱性を修正しました。 -* 4.8.8 - * `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)のディレクトリトラバーサルの脆弱性を修正しました。 -* 4.8.4 - * Node.js 0.10 は、`express.static` と `res.sendfile` に影響を与える特定の状況で `fd` をリークできます。 悪意のある要求は`fd`がリークし、最終的には`EMFILE`エラーとサーバーの応答性が低下する可能性があります。 -* 4.8.0 - * クエリ文字列に非常に高いインデックスを持つ疎行列は、プロセスがメモリ不足になり、サーバーがクラッシュする可能性があります。 - * 非常にネストされたクエリ文字列オブジェクトは、プロセスをブロックし、サーバーが一時的に応答しないようにする可能性があります。 +- 4.21.2 + - 依存関係の `path-to-regexp` が [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w) に対応するように更新されました。 +- 4.21.1 + - 依存関係の `cookie` が [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x) アドレスに更新されました。`res.cookie` を使用すると、アプリケーションに影響する可能性があります。 +- 4.20.0 + - `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796))におけるXSSの脆弱性の修正。 + - 依存関係の `serve-static` が [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p) に更新されました。 + - 依存関係の `send` が [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg) に更新されました。 + - 依存関係の `path-to-regexp` が [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j) に対応するように更新されました。 + - 依存関係の `body-parser` が [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7) を追加するように更新されました。これはURLエンコンデーションが有効になっている場合、アプリケーションに影響する可能性があります。 +- 4.19.0, 4.19.1 + - `res.location` と `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)のオープンリダイレクトの脆弱性を修正しました。 +- 4.17.3 + - 依存関係の `qs` が [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp) に更新されました。 `req.query`、`req.body`、`req.param`という以下のAPIを使用すると、アプリケーションに影響を与える可能性があります。 +- 4.16.0 + - 依存関係の `forwarded` が [vulnerability](https://npmjs.com/advisories/527) に更新されました。 以下の API が使用されている場合、アプリケーションに影響を与える可能性があります: `req.host` 、 `req.hostname` 、 `req.ips` 、 `req.protocol` 。 + - 依存関係の `mime` が [vulnerability](https://npmjs.com/advisories/535) 宛先に更新されましたが、この問題は Express には影響しません。 + - 依存関係の `send` が更新され、[Node.js 8.5.0 脆弱性](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/)に対する保護が提供されました。 これは、Express が特定の Node.js バージョン 8.5.0 で実行されることにのみ影響します。 +- 4.15.5 + - 依存関係の `debug` が [vulnerability](https://snyk.io/vuln/npm:debug:20170905) アドレスに更新されましたが、この問題は Express には影響しません。 + - 依存関係の `fresh` が [vulnerability](https://npmjs.com/advisories/526) に更新されました。 `express.static` 、 `req.fresh` 、 `res.json` 、 `res.json` 、 `res.send` 、 `res.send` 、 `res.sendFile` 、 `res.sendFile` 、 `res.sendStatus` などのAPIが使用されると、アプリケーションに影響します。 +- 4.15.3 + - 依存関係の `ms` が [vulnerability](https://snyk.io/vuln/npm:ms:20170412) に更新されました。 信頼されていない文字列が次の API で `maxAge` オプションに渡されると、アプリケーションに影響を与える可能性があります。`express.static` 、 `res.sendfile` 、 `res.sendFile` です。 +- 4.15.2 + - 依存関係`qs`が [vulnerability]（https://snyk.io/vuln/npm:qs:20170213）アドレスに更新されましたが、この問題はExpressには影響しません。 4.15.2 へのアップデートは良い方法ですが、脆弱性に対処する必要はありません。 +- 4.11.1 + - `express.static`、`res.sendfile`、`res.sendFile`におけるルートパス開示の脆弱性を修正しました。 +- 4.10.7 + - `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)のオープンリダイレクトの脆弱性を修正しました。 +- 4.8.8 + - `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)のディレクトリトラバーサルの脆弱性を修正しました。 +- 4.8.4 + - Node.js 0.10 は、`express.static` と `res.sendfile` に影響を与える特定の状況で `fd` をリークできます。 悪意のある要求は`fd`がリークし、最終的には`EMFILE`エラーとサーバーの応答性が低下する可能性があります。 +- 4.8.0 + - クエリ文字列に非常に高いインデックスを持つ疎行列は、プロセスがメモリ不足になり、サーバーがクラッシュする可能性があります。 + - 非常にネストされたクエリ文字列オブジェクトは、プロセスをブロックし、サーバーが一時的に応答しないようにする可能性があります。 ## 3.x @@ -72,16 +72,16 @@ Express でセキュリティ上の脆弱性を発見したと思われる場合 -* 3.19.1 - * `express.static`、`res.sendfile`、`res.sendFile`におけるルートパス開示の脆弱性を修正しました。 -* 3.19.0 - * `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)のオープンリダイレクトの脆弱性を修正しました。 -* 3.16.10 - * `express.static`におけるディレクトリトラバーサルの脆弱性を修正しました。 -* 3.16.6 - * Node.js 0.10 は、`express.static` と `res.sendfile` に影響を与える特定の状況で `fd` をリークできます。 悪意のある要求は`fd`がリークし、最終的には`EMFILE`エラーとサーバーの応答性が低下する可能性があります。 -* 3.16.0 - * クエリ文字列のインデックスが非常に高いスパース配列は、プロセスがメモリ不足になり、サーバーがクラッシュする可能性があります。 - * 非常にネストされたクエリ文字列オブジェクトは、プロセスをブロックし、サーバーが一時的に応答しないようにする可能性があります。 -* 3.3.0 - * サポートされていないメソッドのオーバーライドを試みた 404 応答は、クロスサイトスクリプティング攻撃の影響を受けやすくなりました。 +- 3.19.1 + - `express.static`、`res.sendfile`、`res.sendFile`におけるルートパス開示の脆弱性を修正しました。 +- 3.19.0 + - `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)のオープンリダイレクトの脆弱性を修正しました。 +- 3.16.10 + - `express.static`におけるディレクトリトラバーサルの脆弱性を修正しました。 +- 3.16.6 + - Node.js 0.10 は、`express.static` と `res.sendfile` に影響を与える特定の状況で `fd` をリークできます。 悪意のある要求は`fd`がリークし、最終的には`EMFILE`エラーとサーバーの応答性が低下する可能性があります。 +- 3.16.0 + - クエリ文字列のインデックスが非常に高いスパース配列は、プロセスがメモリ不足になり、サーバーがクラッシュする可能性があります。 + - 非常にネストされたクエリ文字列オブジェクトは、プロセスをブロックし、サーバーが一時的に応答しないようにする可能性があります。 +- 3.3.0 + - サポートされていないメソッドのオーバーライドを試みた 404 応答は、クロスサイトスクリプティング攻撃の影響を受けやすくなりました。 diff --git a/src/content/pages/ja/guide/database-integration.mdx b/src/content/pages/ja/guide/database-integration.mdx index e091ca9acf..288e0fc5c0 100644 --- a/src/content/pages/ja/guide/database-integration.mdx +++ b/src/content/pages/ja/guide/database-integration.mdx @@ -7,19 +7,19 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Expressアプリケーションにデータベースを接続する機能を追加することは、アプリケーション内のデータベースに適切なNode.jsドライバをロードするだけです。 このドキュメントでは、Express アプリケーションで最も人気のある Node.js モジュールのいくつかを追加して使用する方法を簡単に説明します。 -* [Cassandra](#cassandra) -* [Couchbase](#couchbase) -* [CouchDB](#couchdb) -* [LevelDB](#leveldb) -* [MySQL](#mysql) -* [MongoDB](#mongodb) -* [Neo4j](#neo4j) -* [Oracle](#oracle) -* [PostgreSQL](#postgresql) -* [Redis](#redis) -* [SQL Server](#sql-server) -* [SQLite](#sqlite) -* [Elasticsearch](#elasticsearch) +- [Cassandra](#cassandra) +- [Couchbase](#couchbase) +- [CouchDB](#couchdb) +- [LevelDB](#leveldb) +- [MySQL](#mysql) +- [MongoDB](#mongodb) +- [Neo4j](#neo4j) +- [Oracle](#oracle) +- [PostgreSQL](#postgresql) +- [Redis](#redis) +- [SQL Server](#sql-server) +- [SQLite](#sqlite) +- [Elasticsearch](#elasticsearch) @@ -192,7 +192,7 @@ connection.end(); $ npm install mongodb ``` -### 例 (v2.*) +### 例 (v2.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -210,7 +210,7 @@ MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { }); ``` -### 例 (v3.*) +### 例 (v3.\*) ```js const MongoClient = require('mongodb').MongoClient; diff --git a/src/content/pages/ja/guide/migrating-4.mdx b/src/content/pages/ja/guide/migrating-4.mdx index f726677799..c9afc49bea 100644 --- a/src/content/pages/ja/guide/migrating-4.mdx +++ b/src/content/pages/ja/guide/migrating-4.mdx @@ -40,8 +40,8 @@ Express 4にはいくつかの大きな変更点があります。 こちらもご参照ください: -* [新機能 in 4.x] (https://github.com/expressjs/express/wiki/New-features-in-4.x) -* [Migrating from 3.x to 4.x](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) +- [新機能 in 4.x] (https://github.com/expressjs/express/wiki/New-features-in-4.x) +- [Migrating from 3.x to 4.x](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) ### Express coreとミドルウェアシステムへの変更 @@ -214,8 +214,8 @@ the `router` middleware. ルートの定義方法は変更されていませんが、ルーティングシステムにはルートの整理に役立つ2つの 新機能があります。 -* 新しいメソッド `app.route()` は、ルートパスに対してチェーン可能なルートハンドラを作成します。 -* モジュール式のマウント可能なルートハンドラを作成するための新しいクラス `express.Router` 。 +- 新しいメソッド `app.route()` は、ルートパスに対してチェーン可能なルートハンドラを作成します。 +- モジュール式のマウント可能なルートハンドラを作成するための新しいクラス `express.Router` 。 #### `app.route()`メソッド @@ -304,14 +304,15 @@ middleware that is specific to the route. `http.createServer()` `http`モジュールは、 - （socket.io/SPDY/HTTPS）で直接動作する必要がない限り、もはや必要ありません。 アプリは、`app.listen()`関数を使用して起動できます。 + （socket.io/SPDY/HTTPS）で直接動作する必要がない限り、もはや必要ありません。 + アプリは、`app.listen()`関数を使用して起動できます。 `app.configure()` - `app.configure()`関数が削除されました。 `process.env.NODE_ENV` または - `app.get('env')` 関数を使用して環境を検出し、それに応じてアプリを構成します。 + `app.configure()`関数が削除されました。 `process.env.NODE_ENV` または `app.get('env')` + 関数を使用して環境を検出し、それに応じてアプリを構成します。 @@ -358,8 +359,8 @@ middleware that is specific to the route. `res.setHeader('Set-Cookie', val)` - 機能は基本的なクッキー値の設定に限定されるようになりました。 追加された - 機能には、 `res.cookie()` を使用します。 + 機能は基本的なクッキー値の設定に限定されるようになりました。 追加された 機能には、 + `res.cookie()` を使用します。 @@ -595,9 +596,9 @@ Express 4ジェネレータに更新されます。 コマンドオプションと使用方法は、以下の例外を除き、ほとんど同じままです。 -* `--sessions` オプションを削除しました。 -* `--jshtml` オプションを削除しました。 -* [Hogan.js](http://twitter.github.io/hogan.js/) をサポートするための `--hogan` オプションを追加しました。 +- `--sessions` オプションを削除しました。 +- `--jshtml` オプションを削除しました。 +- [Hogan.js](http://twitter.github.io/hogan.js/) をサポートするための `--hogan` オプションを追加しました。 ### 例 diff --git a/src/content/pages/ja/guide/migrating-5.mdx b/src/content/pages/ja/guide/migrating-5.mdx index ce601d7d1b..c221b9db56 100644 --- a/src/content/pages/ja/guide/migrating-5.mdx +++ b/src/content/pages/ja/guide/migrating-5.mdx @@ -410,12 +410,12 @@ app.get('/user', (req, res) => { **注意:** Express 5, `res. endFile()`は、MIME タイプの検出に`mime-types`パッケージを使用します。これは、一般的なファイルタイプの場合、Express 4とは異なるContent-Type値を返します。 -* JavaScriptファイル (.js): 「application/javascript」の代わりに「text/javascript」を追加しました -* JSON ファイル (.json): 「text/json」の代わりに「application/json」になりました -* CSS ファイル (.css): "text/plain" ではなく "text/css" になりました -* XML ファイル (.xml): "text/xml" の代わりに "application/xml" になりました -* フォントファイル (.woff): "application/font-woff" ではなく "font/woff" になりました -* SVG ファイル (.svg): "application/svg+xml" の代わりに "image/svg+xml" になりました +- JavaScriptファイル (.js): 「application/javascript」の代わりに「text/javascript」を追加しました +- JSON ファイル (.json): 「text/json」の代わりに「application/json」になりました +- CSS ファイル (.css): "text/plain" ではなく "text/css" になりました +- XML ファイル (.xml): "text/xml" の代わりに "application/xml" になりました +- フォントファイル (.woff): "application/font-woff" ではなく "font/woff" になりました +- SVG ファイル (.svg): "application/svg+xml" の代わりに "image/svg+xml" になりました 非推奨の署名は次のコマンドで置き換えることができます: @@ -449,12 +449,12 @@ MIME タイプの値を扱うには、[`mime-types` package](https://github.com/ **重要:** この変更は `express.static.mime` の直接使用だけでなく、 `res.sendFile()` のような MIME タイプの検出に依存する Express メソッドにも影響します。 Express 4から次のMIMEタイプが変更されました。 -* JavaScriptファイル (.js): 「application/javascript」の代わりに「text/javascript」として提供されるようになりました -* JSON ファイル (.json): 「text/json」の代わりに「application/json」として提供されるようになりました -* CSS ファイル (.css): 「text/plain」の代わりに「text/css」として提供されるようになりました -* HTML ファイル (): 単に "text/html" の代わりに "text/html; charset=utf-8" として提供されました -* XML ファイル (.xml): "text/xml" の代わりに "application/xml" として提供されるようになりました -* フォント ファイル (.woff): "application/font-woff" ではなく "font/woff" として提供されるようになりました +- JavaScriptファイル (.js): 「application/javascript」の代わりに「text/javascript」として提供されるようになりました +- JSON ファイル (.json): 「text/json」の代わりに「application/json」として提供されるようになりました +- CSS ファイル (.css): 「text/plain」の代わりに「text/css」として提供されるようになりました +- HTML ファイル (): 単に "text/html" の代わりに "text/html; charset=utf-8" として提供されました +- XML ファイル (.xml): "text/xml" の代わりに "application/xml" として提供されるようになりました +- フォント ファイル (.woff): "application/font-woff" ではなく "font/woff" として提供されるようになりました ```js // v4 @@ -490,7 +490,7 @@ DEBUG=express:*,router,router:* node index.js パスルートマッチング構文は、文字列が`app.all()`、`app.use()`、`app.METHOD()`、`router.all()`、`router.METHOD()`、`router.METHOD()`、`router.METHOD()`、`router.use()` APIに最初のパラメータとして与えられた場合です。 パス文字列が受信リクエストと一致する方法を次のように変更しました: -* ワイルドカード`*`には名前が必要です。パラメータ`:`の動作に一致します。`/*`の代わりに`/*splat`を使用します。 +- ワイルドカード`*`には名前が必要です。パラメータ`:`の動作に一致します。`/*`の代わりに`/*splat`を使用します。 ```js // v4 @@ -516,7 +516,7 @@ app.get('/{*splat}', async (req, res) => { -* オプションの文字 `?` はサポートされなくなりました。代わりに括弧を使用してください。 +- オプションの文字 `?` はサポートされなくなりました。代わりに括弧を使用してください。 ```js // v4 @@ -530,7 +530,7 @@ app.get('/:file{.:ext}', async (req, res) => { }); ``` -* 正規表現文字はサポートされていません。 例: +- 正規表現文字はサポートされていません。 例: ```js app.get('/[discussion|page]/:slug', async (req, res) => { @@ -546,8 +546,8 @@ app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { }); ``` -* いくつかの文字はアップグレード中に混乱を避けるために予約されています (`()[]?+!`), それらをエスケープするために`\`を使用します。 -* パラメータ名が有効な JavaScript 識別子をサポートするようになりました。また、`:"this"` のように引用符で囲まれました。 +- いくつかの文字はアップグレード中に混乱を避けるために予約されています (`()[]?+!`), それらをエスケープするために`\`を使用します。 +- パラメータ名が有効な JavaScript 識別子をサポートするようになりました。また、`:"this"` のように引用符で囲まれました。 ### ミドルウェアとハンドラーから取り扱われる拒否された約束。 diff --git a/src/content/pages/ja/resources/glossary.mdx b/src/content/pages/ja/resources/glossary.mdx index c630340325..cf3b262b4f 100644 --- a/src/content/pages/ja/resources/glossary.mdx +++ b/src/content/pages/ja/resources/glossary.mdx @@ -25,9 +25,9 @@ Node.jsアプリケーション用の高速で、意見が異なる、ミニマ 最後のリクエストハンドラの前に Express ルーティング層によって呼び出される関数 生の要求と最終目的のルートの間に座っています ミドルウェアに関する用語のいくつかの細かい点: -* `var foo = require('middleware')` は Node.js モジュールの *requiring* または *using* と呼ばれます。 `var mw = foo()`という文は通常、ミドルウェアを返します。 -* `app.use(mw)`は、ミドルウェアをグローバルな処理スタックに追加することを呼びます。 -* `app.get('/foo', mw, function (req, res) { ... })` は、ミドルウェアを "GET /foo" 処理の stack_ に追加すると呼ばれます。 +- `var foo = require('middleware')` は Node.js モジュールの _requiring_ または _using_ と呼ばれます。 `var mw = foo()`という文は通常、ミドルウェアを返します。 +- `app.use(mw)`は、ミドルウェアをグローバルな処理スタックに追加することを呼びます。 +- `app.get('/foo', mw, function (req, res) { ... })` は、ミドルウェアを "GET /foo" 処理の stack\_ に追加すると呼ばれます。 ### Node.js diff --git a/src/content/pages/ja/resources/utils.md b/src/content/pages/ja/resources/utils.md index f3268163d1..cb44ec26ca 100644 --- a/src/content/pages/ja/resources/utils.md +++ b/src/content/pages/ja/resources/utils.md @@ -8,15 +8,15 @@ description: Express.jsとNode.jsに関連するユーティリティモジュ [pillarjs](https://github.com/pillarjs) GitHub Organization には、一般的に便利なユーティリティ関数用の多くのモジュール が含まれています。 -| ユーティリティモジュール | 説明 | -| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| [cookies](https://www.npmjs.com/package/cookies) | HTTP(S) Cookie を取得して設定し、改ざんを防ぐために署名できます。Keygrip を使用します。 Node.js HTTP ライブラリまたは Express ミドルウェアとして使用できます。 | -| [csrf](https://www.npmjs.com/package/csrf) | CSRFトークンの作成と検証の背後にあるロジックが含まれています。 このモジュールを使用して、カスタム CSRF ミドルウェアを作成します。 | -| [finalhandler](https://www.npmjs.com/package/finalhandler) | HTTP リクエストに応答するための最後のステップとして呼び出す関数。 | -| [parseurl](https://www.npmjs.com/package/parseurl) | URLをキャッシュで解析します。 | -| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | \`\`/user/:name\`のようなExpressスタイルのパス文字列を正規表現に変換します。 | -| [resolve-path](https://www.npmjs.com/package/resolve-path) | 検証されたルートパスに対して相対パスを解決します。 | -| [router](https://www.npmjs.com/package/router) | シンプルなミドルウェアスタイルのルータ。 | -| [send](https://www.npmjs.com/package/send) | HTTP レスポンスとしてファイルをストリーミングするためのライブラリで、部分的な応答 (範囲)、条件付きの GET ネゴシエーション、および細かいイベントをサポートします。 | +| ユーティリティモジュール | 説明 | +| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [cookies](https://www.npmjs.com/package/cookies) | HTTP(S) Cookie を取得して設定し、改ざんを防ぐために署名できます。Keygrip を使用します。 Node.js HTTP ライブラリまたは Express ミドルウェアとして使用できます。 | +| [csrf](https://www.npmjs.com/package/csrf) | CSRFトークンの作成と検証の背後にあるロジックが含まれています。 このモジュールを使用して、カスタム CSRF ミドルウェアを作成します。 | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | HTTP リクエストに応答するための最後のステップとして呼び出す関数。 | +| [parseurl](https://www.npmjs.com/package/parseurl) | URLをキャッシュで解析します。 | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | \`\`/user/:name\`のようなExpressスタイルのパス文字列を正規表現に変換します。 | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | 検証されたルートパスに対して相対パスを解決します。 | +| [router](https://www.npmjs.com/package/router) | シンプルなミドルウェアスタイルのルータ。 | +| [send](https://www.npmjs.com/package/send) | HTTP レスポンスとしてファイルをストリーミングするためのライブラリで、部分的な応答 (範囲)、条件付きの GET ネゴシエーション、および細かいイベントをサポートします。 | 低レベルの HTTP 関連モジュールについては、 [jshttp](https://github.com/jshttp) を参照してください。 diff --git a/src/content/pages/ja/support.md b/src/content/pages/ja/support.md index f1b922c32e..b413964397 100644 --- a/src/content/pages/ja/support.md +++ b/src/content/pages/ja/support.md @@ -7,14 +7,14 @@ description: 現在メンテナンスされているバージョンや終了ポ EOL (終了) _may_ のバージョンは、重大なセキュリティ脆弱性の更新を受け取ります。 しかし、Expressチームは保証を提供しておらず、見つかった問題の修正やリリースを計画していません。 -| メジャーバージョン | 最小Node.js バージョン | サポート開始日 | サポート終了日 | -| ------------------------------------------- | -------------------------------------- | ---------- | ---------- | -| [**v5.x**](/en/5x/api) | 18 | 2024年9月 | **進行中** | -| [**v4.x**](/en/4x/api) | 0.10.0 | 2014 年 4 月 | **進行中** | -| [**v3.x**](/en/3x/api) | 0.8.0 | 2012年10月 | 2015 年 7 月 | -| [**v2.x**](/2x/) | 0.4.1 | 2011 年 3 月 | 2012 年 7 月 | -| **v1.x** | 0.2.0 | 2010年12月 | 2011 年 3 月 | -| **v0.14.x** | 0.1.98 | 2010年12月 | 2010年12月 | +| メジャーバージョン | 最小Node.js バージョン | サポート開始日 | サポート終了日 | +| ---------------------- | ---------------------- | -------------- | -------------- | +| [**v5.x**](/en/5x/api) | 18 | 2024年9月 | **進行中** | +| [**v4.x**](/en/4x/api) | 0.10.0 | 2014 年 4 月 | **進行中** | +| [**v3.x**](/en/3x/api) | 0.8.0 | 2012年10月 | 2015 年 7 月 | +| [**v2.x**](/2x/) | 0.4.1 | 2011 年 3 月 | 2012 年 7 月 | +| **v1.x** | 0.2.0 | 2010年12月 | 2011 年 3 月 | +| **v0.14.x** | 0.1.98 | 2010年12月 | 2010年12月 | ## 商用サポートオプション diff --git a/src/content/pages/ko/advanced/best-practice-security.mdx b/src/content/pages/ko/advanced/best-practice-security.mdx index fa7b7622bb..4ca68c5122 100644 --- a/src/content/pages/ko/advanced/best-practice-security.mdx +++ b/src/content/pages/ko/advanced/best-practice-security.mdx @@ -1,11 +1,11 @@ --- -title: "Production Best Practices: Security" +title: 'Production Best Practices: Security' description: Discover crucial security best practices for Express apps in production, including using TLS, input validation, secure cookies, and preventing vulnerabilities. --- import Alert from '@components/primitives/Alert/Alert.astro'; -The term *"production"* refers to the stage in the software lifecycle when an application or API is generally available to its end-users or consumers. In contrast, in the *"development"* stage, you're still actively writing and testing code, and the application is not open to external access. The corresponding system environments are known as *production* and *development* environments, respectively. +The term _"production"_ refers to the stage in the software lifecycle when an application or API is generally available to its end-users or consumers. In contrast, in the _"development"_ stage, you're still actively writing and testing code, and the application is not open to external access. The corresponding system environments are known as _production_ and _development_ environments, respectively. Development and production environments are usually set up differently and have vastly different requirements. What's fine in development may not be acceptable in production. For example, in a development environment you may want verbose logging of errors for debugging, while the same behavior can become a security concern in a production environment. And in development, you don't need to worry about scalability, reliability, and performance, while those concerns become critical in production. @@ -18,21 +18,21 @@ Policies and Procedures. Security best practices for Express applications in production include: -* [Production Best Practices: Security](#production-best-practices-security) - * [Overview](#overview) - * [Don't use deprecated or vulnerable versions of Express](#dont-use-deprecated-or-vulnerable-versions-of-express) - * [Use TLS](#use-tls) - * [Do not trust user input](#do-not-trust-user-input) - * [Prevent open redirects](#prevent-open-redirects) - * [Use Helmet](#use-helmet) - * [Reduce fingerprinting](#reduce-fingerprinting) - * [Use cookies securely](#use-cookies-securely) - * [Don't use the default session cookie name](#dont-use-the-default-session-cookie-name) - * [Set cookie security options](#set-cookie-security-options) - * [Prevent brute-force attacks against authorization](#prevent-brute-force-attacks-against-authorization) - * [Ensure your dependencies are secure](#ensure-your-dependencies-are-secure) - * [Avoid other known vulnerabilities](#avoid-other-known-vulnerabilities) - * [Additional considerations](#additional-considerations) +- [Production Best Practices: Security](#production-best-practices-security) + - [Overview](#overview) + - [Don't use deprecated or vulnerable versions of Express](#dont-use-deprecated-or-vulnerable-versions-of-express) + - [Use TLS](#use-tls) + - [Do not trust user input](#do-not-trust-user-input) + - [Prevent open redirects](#prevent-open-redirects) + - [Use Helmet](#use-helmet) + - [Reduce fingerprinting](#reduce-fingerprinting) + - [Use cookies securely](#use-cookies-securely) + - [Don't use the default session cookie name](#dont-use-the-default-session-cookie-name) + - [Set cookie security options](#set-cookie-security-options) + - [Prevent brute-force attacks against authorization](#prevent-brute-force-attacks-against-authorization) + - [Ensure your dependencies are secure](#ensure-your-dependencies-are-secure) + - [Avoid other known vulnerabilities](#avoid-other-known-vulnerabilities) + - [Additional considerations](#additional-considerations) ## Don't use deprecated or vulnerable versions of Express @@ -44,7 +44,7 @@ Also ensure you are not using any of the vulnerable Express versions listed on t If your app deals with or transmits sensitive data, use [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) to secure the connection and the data. This technology encrypts data before it is sent from the client to the server, thus preventing some common (and easy) hacks. Although Ajax and POST requests might not be visibly obvious and seem "hidden" in browsers, their network traffic is vulnerable to [packet sniffing](https://en.wikipedia.org/wiki/Packet_analyzer) and [man-in-the-middle attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). -You may be familiar with Secure Socket Layer (SSL) encryption. [TLS is simply the next progression of SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). In other words, if you were using SSL before, consider upgrading to TLS. In general, we recommend Nginx to handle TLS. For a good reference to configure TLS on Nginx (and other servers), see [Recommended Server Configurations (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). +You may be familiar with Secure Socket Layer (SSL) encryption. [TLS is simply the next progression of SSL](). In other words, if you were using SSL before, consider upgrading to TLS. In general, we recommend Nginx to handle TLS. For a good reference to configure TLS on Nginx (and other servers), see [Recommended Server Configurations (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). Also, a handy tool to get a free TLS certificate is [Let's Encrypt](https://letsencrypt.org/about/), a free, automated, and open certificate authority (CA) provided by the [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). @@ -55,7 +55,7 @@ Ultimately, the responsibility for validating and correctly handling the types o ### Prevent open redirects -An example of potentially dangerous user input is an *open redirect*, where an application accepts a URL as user input (often in the URL query, for example `?url=https://example.com`) and uses `res.redirect` to set the `location` header and +An example of potentially dangerous user input is an _open redirect_, where an application accepts a URL as user input (often in the URL query, for example `?url=https://example.com`) and uses `res.redirect` to set the `location` header and return a 3xx status. An application must validate that it supports redirecting to the incoming URL to avoid sending users to malicious links such as phishing websites, among other risks. @@ -81,19 +81,19 @@ app.use((req, res) => { Helmet is a middleware function that sets security-related HTTP response headers. Helmet sets the following headers by default: -* `Content-Security-Policy`: A powerful allow-list of what can happen on your page which mitigates many attacks -* `Cross-Origin-Opener-Policy`: Helps process-isolate your page -* `Cross-Origin-Resource-Policy`: Blocks others from loading your resources cross-origin -* `Origin-Agent-Cluster`: Changes process isolation to be origin-based -* `Referrer-Policy`: Controls the [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) header -* `Strict-Transport-Security`: Tells browsers to prefer HTTPS -* `X-Content-Type-Options`: Avoids [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) -* `X-DNS-Prefetch-Control`: Controls DNS prefetching -* `X-Download-Options`: Forces downloads to be saved (Internet Explorer only) -* `X-Frame-Options`: Legacy header that mitigates [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) attacks -* `X-Permitted-Cross-Domain-Policies`: Controls cross-domain behavior for Adobe products, like Acrobat -* `X-Powered-By`: Info about the web server. Removed because it could be used in simple attacks -* `X-XSS-Protection`: Legacy header that tries to mitigate [XSS attacks](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), but makes things worse, so Helmet disables it +- `Content-Security-Policy`: A powerful allow-list of what can happen on your page which mitigates many attacks +- `Cross-Origin-Opener-Policy`: Helps process-isolate your page +- `Cross-Origin-Resource-Policy`: Blocks others from loading your resources cross-origin +- `Origin-Agent-Cluster`: Changes process isolation to be origin-based +- `Referrer-Policy`: Controls the [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) header +- `Strict-Transport-Security`: Tells browsers to prefer HTTPS +- `X-Content-Type-Options`: Avoids [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +- `X-DNS-Prefetch-Control`: Controls DNS prefetching +- `X-Download-Options`: Forces downloads to be saved (Internet Explorer only) +- `X-Frame-Options`: Legacy header that mitigates [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) attacks +- `X-Permitted-Cross-Domain-Policies`: Controls cross-domain behavior for Adobe products, like Acrobat +- `X-Powered-By`: Info about the web server. Removed because it could be used in simple attacks +- `X-XSS-Protection`: Legacy header that tries to mitigate [XSS attacks](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), but makes things worse, so Helmet disables it Each header can be configured or disabled. To read more about it please go to [its documentation website][helmet]. @@ -164,8 +164,8 @@ To ensure cookies don't open your app to exploits, don't use the default session There are two main middleware cookie session modules: -* [express-session](https://www.npmjs.com/package/express-session) that replaces `express.session` middleware built-in to Express 3.x. -* [cookie-session](https://www.npmjs.com/package/cookie-session) that replaces `express.cookieSession` middleware built-in to Express 3.x. +- [express-session](https://www.npmjs.com/package/express-session) that replaces `express.session` middleware built-in to Express 3.x. +- [cookie-session](https://www.npmjs.com/package/cookie-session) that replaces `express.cookieSession` middleware built-in to Express 3.x. The main difference between these two modules is how they save cookie session data. The [express-session](https://www.npmjs.com/package/express-session) middleware stores session data on the server; it only saves the session ID in the cookie itself, not session data. By default, it uses in-memory storage and is not designed for a production environment. In production, you'll need to set up a scalable session-store; see the list of [compatible session stores](https://github.com/expressjs/session#compatible-session-stores). @@ -192,11 +192,11 @@ app.use( Set the following cookie options to enhance security: -* `secure` - Ensures the browser only sends the cookie over HTTPS. -* `httpOnly` - Ensures the cookie is sent only over HTTP(S), not client JavaScript, helping to protect against cross-site scripting attacks. -* `domain` - indicates the domain of the cookie; use it to compare against the domain of the server in which the URL is being requested. If they match, then check the path attribute next. -* `path` - indicates the path of the cookie; use it to compare against the request path. If this and domain match, then send the cookie in the request. -* `expires` - use to set expiration date for persistent cookies. +- `secure` - Ensures the browser only sends the cookie over HTTPS. +- `httpOnly` - Ensures the cookie is sent only over HTTP(S), not client JavaScript, helping to protect against cross-site scripting attacks. +- `domain` - indicates the domain of the cookie; use it to compare against the domain of the server in which the URL is being requested. If they match, then check the path attribute next. +- `path` - indicates the path of the cookie; use it to compare against the request path. If this and domain match, then send the cookie in the request. +- `expires` - use to set expiration date for persistent cookies. Here is an example using [cookie-session](https://www.npmjs.com/package/cookie-session) middleware: @@ -267,10 +267,10 @@ Finally, Express apps—like any other web apps—can be vulnerable to a Here are some further recommendations from the excellent [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/). Refer to that blog post for all the details on these recommendations: -* Always filter and sanitize user input to protect against cross-site scripting (XSS) and command injection attacks. -* Defend against SQL injection attacks by using parameterized queries or prepared statements. -* Use the open-source [sqlmap](http://sqlmap.org/) tool to detect SQL injection vulnerabilities in your app. -* Use the [nmap](https://nmap.org/) and [sslyze](https://github.com/nabla-c0d3/sslyze) tools to test the configuration of your SSL ciphers, keys, and renegotiation as well as the validity of your certificate. -* Use [safe-regex](https://www.npmjs.com/package/safe-regex) to ensure your regular expressions are not susceptible to [regular expression denial of service](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) attacks. +- Always filter and sanitize user input to protect against cross-site scripting (XSS) and command injection attacks. +- Defend against SQL injection attacks by using parameterized queries or prepared statements. +- Use the open-source [sqlmap](http://sqlmap.org/) tool to detect SQL injection vulnerabilities in your app. +- Use the [nmap](https://nmap.org/) and [sslyze](https://github.com/nabla-c0d3/sslyze) tools to test the configuration of your SSL ciphers, keys, and renegotiation as well as the validity of your certificate. +- Use [safe-regex](https://www.npmjs.com/package/safe-regex) to ensure your regular expressions are not susceptible to [regular expression denial of service](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) attacks. [helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/ko/advanced/security-updates.mdx b/src/content/pages/ko/advanced/security-updates.mdx index dfed519ec6..c5ea3f336a 100644 --- a/src/content/pages/ko/advanced/security-updates.mdx +++ b/src/content/pages/ko/advanced/security-updates.mdx @@ -24,42 +24,42 @@ Policies and Procedures. ## 4.x -* 4.21.2 - * The dependency `path-to-regexp` has been updated to address a [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). -* 4.21.1 - * The dependency `cookie` has been updated to address a [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), This may affect your application if you use `res.cookie`. -* 4.20.0 - * Fixed XSS vulnerability in `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). - * The dependency `serve-static` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). - * The dependency `send` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). - * The dependency `path-to-regexp` has been updated to address a [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). - * The dependency `body-parser` has been updated to addres a [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), This may affect your application if you had url enconding activated. -* 4.19.0, 4.19.1 - * Fixed open redirect vulnerability in `res.location` and `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). -* 4.17.3 - * The dependency `qs` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). This may affect your application if the following APIs are used: `req.query`, `req.body`, `req.param`. -* 4.16.0 - * The dependency `forwarded` has been updated to address a [vulnerability](https://npmjs.com/advisories/527). This may affect your application if the following APIs are used: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. - * The dependency `mime` has been updated to address a [vulnerability](https://npmjs.com/advisories/535), but this issue does not impact Express. - * The dependency `send` has been updated to provide a protection against a [Node.js 8.5.0 vulnerability](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). This only impacts running Express on the specific Node.js version 8.5.0. -* 4.15.5 - * The dependency `debug` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:debug:20170905), but this issue does not impact Express. - * The dependency `fresh` has been updated to address a [vulnerability](https://npmjs.com/advisories/526). This will affect your application if the following APIs are used: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. -* 4.15.3 - * The dependency `ms` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:ms:20170412). This may affect your application if untrusted string input is passed to the `maxAge` option in the following APIs: `express.static`, `res.sendfile`, and `res.sendFile`. -* 4.15.2 - * The dependency `qs` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:qs:20170213), but this issue does not impact Express. Updating to 4.15.2 is a good practice, but not required to address the vulnerability. -* 4.11.1 - * Fixed root path disclosure vulnerability in `express.static`, `res.sendfile`, and `res.sendFile` -* 4.10.7 - * Fixed open redirect vulnerability in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 4.8.8 - * Fixed directory traversal vulnerabilities in `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). -* 4.8.4 - * Node.js 0.10 can leak `fd`s in certain situations that affect `express.static` and `res.sendfile`. Malicious requests could cause `fd`s to leak and eventually lead to `EMFILE` errors and server unresponsiveness. -* 4.8.0 - * Sparse arrays that have extremely high indexes in the query string could cause the process to run out of memory and crash the server. - * Extremely nested query string objects could cause the process to block and make the server unresponsive temporarily. +- 4.21.2 + - The dependency `path-to-regexp` has been updated to address a [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +- 4.21.1 + - The dependency `cookie` has been updated to address a [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), This may affect your application if you use `res.cookie`. +- 4.20.0 + - Fixed XSS vulnerability in `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + - The dependency `serve-static` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). + - The dependency `send` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + - The dependency `path-to-regexp` has been updated to address a [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + - The dependency `body-parser` has been updated to addres a [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), This may affect your application if you had url enconding activated. +- 4.19.0, 4.19.1 + - Fixed open redirect vulnerability in `res.location` and `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +- 4.17.3 + - The dependency `qs` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). This may affect your application if the following APIs are used: `req.query`, `req.body`, `req.param`. +- 4.16.0 + - The dependency `forwarded` has been updated to address a [vulnerability](https://npmjs.com/advisories/527). This may affect your application if the following APIs are used: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + - The dependency `mime` has been updated to address a [vulnerability](https://npmjs.com/advisories/535), but this issue does not impact Express. + - The dependency `send` has been updated to provide a protection against a [Node.js 8.5.0 vulnerability](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). This only impacts running Express on the specific Node.js version 8.5.0. +- 4.15.5 + - The dependency `debug` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:debug:20170905), but this issue does not impact Express. + - The dependency `fresh` has been updated to address a [vulnerability](https://npmjs.com/advisories/526). This will affect your application if the following APIs are used: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. +- 4.15.3 + - The dependency `ms` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:ms:20170412). This may affect your application if untrusted string input is passed to the `maxAge` option in the following APIs: `express.static`, `res.sendfile`, and `res.sendFile`. +- 4.15.2 + - The dependency `qs` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:qs:20170213), but this issue does not impact Express. Updating to 4.15.2 is a good practice, but not required to address the vulnerability. +- 4.11.1 + - Fixed root path disclosure vulnerability in `express.static`, `res.sendfile`, and `res.sendFile` +- 4.10.7 + - Fixed open redirect vulnerability in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 4.8.8 + - Fixed directory traversal vulnerabilities in `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +- 4.8.4 + - Node.js 0.10 can leak `fd`s in certain situations that affect `express.static` and `res.sendfile`. Malicious requests could cause `fd`s to leak and eventually lead to `EMFILE` errors and server unresponsiveness. +- 4.8.0 + - Sparse arrays that have extremely high indexes in the query string could cause the process to run out of memory and crash the server. + - Extremely nested query string objects could cause the process to block and make the server unresponsive temporarily. ## 3.x @@ -72,16 +72,16 @@ If you are unable to upgrade past 3.x, please consider [Commercial Support Optio -* 3.19.1 - * Fixed root path disclosure vulnerability in `express.static`, `res.sendfile`, and `res.sendFile` -* 3.19.0 - * Fixed open redirect vulnerability in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 3.16.10 - * Fixed directory traversal vulnerabilities in `express.static`. -* 3.16.6 - * Node.js 0.10 can leak `fd`s in certain situations that affect `express.static` and `res.sendfile`. Malicious requests could cause `fd`s to leak and eventually lead to `EMFILE` errors and server unresponsiveness. -* 3.16.0 - * Sparse arrays that have extremely high indexes in query string could cause the process to run out of memory and crash the server. - * Extremely nested query string objects could cause the process to block and make the server unresponsive temporarily. -* 3.3.0 - * The 404 response of an unsupported method override attempt was susceptible to cross-site scripting attacks. +- 3.19.1 + - Fixed root path disclosure vulnerability in `express.static`, `res.sendfile`, and `res.sendFile` +- 3.19.0 + - Fixed open redirect vulnerability in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 3.16.10 + - Fixed directory traversal vulnerabilities in `express.static`. +- 3.16.6 + - Node.js 0.10 can leak `fd`s in certain situations that affect `express.static` and `res.sendfile`. Malicious requests could cause `fd`s to leak and eventually lead to `EMFILE` errors and server unresponsiveness. +- 3.16.0 + - Sparse arrays that have extremely high indexes in query string could cause the process to run out of memory and crash the server. + - Extremely nested query string objects could cause the process to block and make the server unresponsive temporarily. +- 3.3.0 + - The 404 response of an unsupported method override attempt was susceptible to cross-site scripting attacks. diff --git a/src/content/pages/ko/guide/database-integration.mdx b/src/content/pages/ko/guide/database-integration.mdx index 9a97d66c47..b0855e4a2a 100644 --- a/src/content/pages/ko/guide/database-integration.mdx +++ b/src/content/pages/ko/guide/database-integration.mdx @@ -7,19 +7,19 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Adding the capability to connect databases to Express apps is just a matter of loading an appropriate Node.js driver for the database in your app. This document briefly explains how to add and use some of the most popular Node.js modules for database systems in your Express app: -* [Cassandra](#cassandra) -* [Couchbase](#couchbase) -* [CouchDB](#couchdb) -* [LevelDB](#leveldb) -* [MySQL](#mysql) -* [MongoDB](#mongodb) -* [Neo4j](#neo4j) -* [Oracle](#oracle) -* [PostgreSQL](#postgresql) -* [Redis](#redis) -* [SQL Server](#sql-server) -* [SQLite](#sqlite) -* [Elasticsearch](#elasticsearch) +- [Cassandra](#cassandra) +- [Couchbase](#couchbase) +- [CouchDB](#couchdb) +- [LevelDB](#leveldb) +- [MySQL](#mysql) +- [MongoDB](#mongodb) +- [Neo4j](#neo4j) +- [Oracle](#oracle) +- [PostgreSQL](#postgresql) +- [Redis](#redis) +- [SQL Server](#sql-server) +- [SQLite](#sqlite) +- [Elasticsearch](#elasticsearch) @@ -192,7 +192,7 @@ connection.end(); $ npm install mongodb ``` -### Example (v2.*) +### Example (v2.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -210,7 +210,7 @@ MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { }); ``` -### Example (v3.*) +### Example (v3.\*) ```js const MongoClient = require('mongodb').MongoClient; diff --git a/src/content/pages/ko/guide/migrating-4.mdx b/src/content/pages/ko/guide/migrating-4.mdx index 619682818a..42a1b63163 100644 --- a/src/content/pages/ko/guide/migrating-4.mdx +++ b/src/content/pages/ko/guide/migrating-4.mdx @@ -5,7 +5,7 @@ description: A guide to migrating your Express.js applications from version 3 to import Alert from '@components/primitives/Alert/Alert.astro'; -Express 4 is a breaking change from Express 3. That means an existing Express 3 app will *not* work if you update the Express version in its dependencies. +Express 4 is a breaking change from Express 3. That means an existing Express 3 app will _not_ work if you update the Express version in its dependencies. This article covers: @@ -40,8 +40,8 @@ There are several significant changes in Express 4: See also: -* [New features in 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) -* [Migrating from 3.x to 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) +- [New features in 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +- [Migrating from 3.x to 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) ### Changes to Express core and middleware system @@ -214,8 +214,8 @@ the `router` middleware. The way you define routes is unchanged, but the routing system has two new features to help organize your routes: -* A new method, `app.route()`, to create chainable route handlers for a route path. -* A new class, `express.Router`, to create modular mountable route handlers. +- A new method, `app.route()`, to create chainable route handlers for a route path. +- A new class, `express.Router`, to create modular mountable route handlers. #### `app.route()` method @@ -595,9 +595,9 @@ Express 4 generator. Command options and use largely remain the same, with the following exceptions: -* Removed the `--sessions` option. -* Removed the `--jshtml` option. -* Added the `--hogan` option to support [Hogan.js](http://twitter.github.io/hogan.js/). +- Removed the `--sessions` option. +- Removed the `--jshtml` option. +- Added the `--hogan` option to support [Hogan.js](http://twitter.github.io/hogan.js/). ### Example diff --git a/src/content/pages/ko/guide/migrating-5.mdx b/src/content/pages/ko/guide/migrating-5.mdx index 2a035c4e04..dac703c953 100644 --- a/src/content/pages/ko/guide/migrating-5.mdx +++ b/src/content/pages/ko/guide/migrating-5.mdx @@ -410,12 +410,12 @@ The `res.sendfile()` function has been replaced by a camel-cased version `res.se **Note:** In Express 5, `res.sendFile()` uses the `mime-types` package for MIME type detection, which returns different Content-Type values than Express 4 for several common file types: -* JavaScript files (.js): now "text/javascript" instead of "application/javascript" -* JSON files (.json): now "application/json" instead of "text/json" -* CSS files (.css): now "text/css" instead of "text/plain" -* XML files (.xml): now "application/xml" instead of "text/xml" -* Font files (.woff): now "font/woff" instead of "application/font-woff" -* SVG files (.svg): now "image/svg+xml" instead of "application/svg+xml" +- JavaScript files (.js): now "text/javascript" instead of "application/javascript" +- JSON files (.json): now "application/json" instead of "text/json" +- CSS files (.css): now "text/css" instead of "text/plain" +- XML files (.xml): now "application/xml" instead of "text/xml" +- Font files (.woff): now "font/woff" instead of "application/font-woff" +- SVG files (.svg): now "image/svg+xml" instead of "application/svg+xml" You can replace the deprecated signatures with the following command: @@ -449,12 +449,12 @@ Use the [`mime-types` package](https://github.com/jshttp/mime-types) to work wit **Important:** This change affects not only direct usage of `express.static.mime` but also other Express methods that rely on MIME type detection, such as `res.sendFile()`. The following MIME types have changed from Express 4: -* JavaScript files (.js): now served as "text/javascript" instead of "application/javascript" -* JSON files (.json): now served as "application/json" instead of "text/json" -* CSS files (.css): now served as "text/css" instead of "text/plain" -* HTML files (): now served as "text/html; charset=utf-8" instead of just "text/html" -* XML files (.xml): now served as "application/xml" instead of "text/xml" -* Font files (.woff): now served as "font/woff" instead of "application/font-woff" +- JavaScript files (.js): now served as "text/javascript" instead of "application/javascript" +- JSON files (.json): now served as "application/json" instead of "text/json" +- CSS files (.css): now served as "text/css" instead of "text/plain" +- HTML files (): now served as "text/html; charset=utf-8" instead of just "text/html" +- XML files (.xml): now served as "application/xml" instead of "text/xml" +- Font files (.woff): now served as "font/woff" instead of "application/font-woff" ```js // v4 @@ -490,7 +490,7 @@ DEBUG=express:*,router,router:* node index.js Path route matching syntax is when a string is supplied as the first parameter to the `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, and `router.use()` APIs. The following changes have been made to how the path string is matched to an incoming request: -* The wildcard `*` must have a name, matching the behavior of parameters `:`, use `/*splat` instead of `/*` +- The wildcard `*` must have a name, matching the behavior of parameters `:`, use `/*splat` instead of `/*` ```js // v4 @@ -516,7 +516,7 @@ app.get('/{*splat}', async (req, res) => { -* The optional character `?` is no longer supported, use braces instead. +- The optional character `?` is no longer supported, use braces instead. ```js // v4 @@ -530,7 +530,7 @@ app.get('/:file{.:ext}', async (req, res) => { }); ``` -* Regexp characters are not supported. For example: +- Regexp characters are not supported. For example: ```js app.get('/[discussion|page]/:slug', async (req, res) => { @@ -546,8 +546,8 @@ app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { }); ``` -* Some characters have been reserved to avoid confusion during upgrade (`()[]?+!`), use `\` to escape them. -* Parameter names now support valid JavaScript identifiers, or quoted like `:"this"`. +- Some characters have been reserved to avoid confusion during upgrade (`()[]?+!`), use `\` to escape them. +- Parameter names now support valid JavaScript identifiers, or quoted like `:"this"`. ### Rejected promises handled from middleware and handlers diff --git a/src/content/pages/ko/resources/glossary.mdx b/src/content/pages/ko/resources/glossary.mdx index e94e59ab60..c40a0a2e15 100644 --- a/src/content/pages/ko/resources/glossary.mdx +++ b/src/content/pages/ko/resources/glossary.mdx @@ -25,9 +25,9 @@ A multi-platform support library which focuses on asynchronous I/O, primarily de A function that is invoked by the Express routing layer before the final request handler, and thus sits in the middle between a raw request and the final intended route. A few fine points of terminology around middleware: -* `var foo = require('middleware')` is called *requiring* or *using* a Node.js module. Then the statement `var mw = foo()` typically returns the middleware. -* `app.use(mw)` is called *adding the middleware to the global processing stack*. -* `app.get('/foo', mw, function (req, res) { ... })` is called *adding the middleware to the "GET /foo" processing stack*. +- `var foo = require('middleware')` is called _requiring_ or _using_ a Node.js module. Then the statement `var mw = foo()` typically returns the middleware. +- `app.use(mw)` is called _adding the middleware to the global processing stack_. +- `app.get('/foo', mw, function (req, res) { ... })` is called _adding the middleware to the "GET /foo" processing stack_. ### Node.js diff --git a/src/content/pages/ko/resources/utils.md b/src/content/pages/ko/resources/utils.md index 3a8b0a5be1..739b352f3e 100644 --- a/src/content/pages/ko/resources/utils.md +++ b/src/content/pages/ko/resources/utils.md @@ -8,15 +8,15 @@ description: Discover utility modules related to Express.js and Node.js, includi The [pillarjs](https://github.com/pillarjs) GitHub organization contains a number of modules for utility functions that may be generally useful. -| Utility modules | Description | -| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Utility modules | Description | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | [cookies](https://www.npmjs.com/package/cookies) | Get and set HTTP(S) cookies that can be signed to prevent tampering, using Keygrip. Can be used with the Node.js HTTP library or as Express middleware. | -| [csrf](https://www.npmjs.com/package/csrf) | Contains the logic behind CSRF token creation and verification. Use this module to create custom CSRF middleware. | -| [finalhandler](https://www.npmjs.com/package/finalhandler) | Function to invoke as the final step to respond to HTTP request. | -| [parseurl](https://www.npmjs.com/package/parseurl) | Parse a URL with caching. | -| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Turn an Express-style path string such as \`\`/user/:name\` into a regular expression. | -| [resolve-path](https://www.npmjs.com/package/resolve-path) | Resolves a relative path against a root path with validation. | -| [router](https://www.npmjs.com/package/router) | Simple middleware-style router. | -| [send](https://www.npmjs.com/package/send) | Library for streaming files as a HTTP response, with support for partial responses (ranges), conditional-GET negotiation, and granular events. | +| [csrf](https://www.npmjs.com/package/csrf) | Contains the logic behind CSRF token creation and verification. Use this module to create custom CSRF middleware. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Function to invoke as the final step to respond to HTTP request. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Parse a URL with caching. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Turn an Express-style path string such as \`\`/user/:name\` into a regular expression. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Resolves a relative path against a root path with validation. | +| [router](https://www.npmjs.com/package/router) | Simple middleware-style router. | +| [send](https://www.npmjs.com/package/send) | Library for streaming files as a HTTP response, with support for partial responses (ranges), conditional-GET negotiation, and granular events. | For additional low-level HTTP-related modules, see [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/ko/support.md b/src/content/pages/ko/support.md index 68763b76f0..9e59b0976b 100644 --- a/src/content/pages/ko/support.md +++ b/src/content/pages/ko/support.md @@ -7,14 +7,14 @@ Only the latest version of any given major release line is supported. Versions that are EOL (end-of-life) _may_ receive updates for critical security vulnerabilities, but the Express team offers no guarantee and does not plan to address or release fixes for any issues found. -| Major Version | Minimum Node.js Version | Support Start Date | Support End Date | -| ------------------------------------------- | --------------------------------------- | ------------------ | ---------------- | -| [**v5.x**](/en/5x/api) | 18 | September 2024 | **ongoing** | -| [**v4.x**](/en/4x/api) | 0.10.0 | April 2014 | **ongoing** | -| [**v3.x**](/en/3x/api) | 0.8.0 | October 2012 | July 2015 | -| [**v2.x**](/2x/) | 0.4.1 | March 2011 | July 2012 | -| **v1.x** | 0.2.0 | December 2010 | March 2011 | -| **v0.14.x** | 0.1.98 | December 2010 | December 2010 | +| Major Version | Minimum Node.js Version | Support Start Date | Support End Date | +| ---------------------- | ----------------------- | ------------------ | ---------------- | +| [**v5.x**](/en/5x/api) | 18 | September 2024 | **ongoing** | +| [**v4.x**](/en/4x/api) | 0.10.0 | April 2014 | **ongoing** | +| [**v3.x**](/en/3x/api) | 0.8.0 | October 2012 | July 2015 | +| [**v2.x**](/2x/) | 0.4.1 | March 2011 | July 2012 | +| **v1.x** | 0.2.0 | December 2010 | March 2011 | +| **v0.14.x** | 0.1.98 | December 2010 | December 2010 | ## Commercial Support Options diff --git a/src/content/pages/pt-br/advanced/best-practice-security.mdx b/src/content/pages/pt-br/advanced/best-practice-security.mdx index b045b74220..16d04ed456 100644 --- a/src/content/pages/pt-br/advanced/best-practice-security.mdx +++ b/src/content/pages/pt-br/advanced/best-practice-security.mdx @@ -1,11 +1,11 @@ --- -title: "Melhores Práticas de Produção: Segurança" +title: 'Melhores Práticas de Produção: Segurança' description: Descubra as melhores práticas de segurança cruciais para aplicativos Express em produção, incluindo o uso de TLS, validação de entrada, cookies seguros e prevenção de vulnerabilidades. --- import Alert from '@components/primitives/Alert/Alert.astro'; -O termo *"produção"* se refere ao estágio no ciclo de vida do software quando uma aplicação ou API está geralmente disponível para seus usuários finais ou consumidores. Em contraste, na etapa "development"__ , você ainda está escrevendo e testando o código, e o aplicativo não está aberto para acesso externo. Os ambientes de sistema correspondentes são conhecidos como ambientes de *produção* e *desenvolvimento*, respectivamente. +O termo _"produção"_ se refere ao estágio no ciclo de vida do software quando uma aplicação ou API está geralmente disponível para seus usuários finais ou consumidores. Em contraste, na etapa "development"\_\_ , você ainda está escrevendo e testando o código, e o aplicativo não está aberto para acesso externo. Os ambientes de sistema correspondentes são conhecidos como ambientes de _produção_ e _desenvolvimento_, respectivamente. Os ambientes de desenvolvimento e de produção são concebidos de forma diferente e têm requisitos muito diferentes. O que há de bom no desenvolvimento pode não ser aceitável na produção. Por exemplo, em um ambiente de desenvolvimento, você pode querer um registro detalhado de erros para depuração, enquanto o mesmo comportamento pode se tornar uma preocupação de segurança em ambiente de produção. E no desenvolvimento, você não precisa se preocupar com escalabilidade, confiabilidade e desempenho, enquanto esses problemas se tornam críticos em produção. @@ -18,21 +18,21 @@ Políticas e Procedimentos. As melhores práticas de segurança para aplicações Expressas na produção incluem: -* [Práticas de Melhor Produção: Segurança](#production-best-practices-security) - * [Overview](#overview) - * [Não usar versões descontinuadas ou vulneráveis do Express](#dont-use-deprecated-or-vulnerable-versions-of-express) - * [Usar TLS](#use-tls) - * [Não confie na entrada do usuário](#do-not-trust-user-input) - * [Impedir redirecionamentos abertos](#prevent-open-redirects) - * [Usar capacete](#use-helmet) - * [Reduzir impressão digital](#reduce-fingerprinting) - * [Usar cookies de forma segura](#use-cookies-securely) - * [Não usar o nome padrão de cookie da sessão](#dont-use-the-default-session-cookie-name) - * [Definir opções de segurança de cookies](#set-cookie-security-options) - * [Impedir ataques brute-force contra a autorização](#prevent-brute-force-attacks-against-authorization) - * [Garanta que suas dependências sejam seguras](#ensure-your-dependencies-are-secure) - * [Evitar outras vulnerabilidades conhecidas](#avoid-other-known-vulnerabilities) - * [Considerações adicionais](#additional-considerations) +- [Práticas de Melhor Produção: Segurança](#production-best-practices-security) + - [Overview](#overview) + - [Não usar versões descontinuadas ou vulneráveis do Express](#dont-use-deprecated-or-vulnerable-versions-of-express) + - [Usar TLS](#use-tls) + - [Não confie na entrada do usuário](#do-not-trust-user-input) + - [Impedir redirecionamentos abertos](#prevent-open-redirects) + - [Usar capacete](#use-helmet) + - [Reduzir impressão digital](#reduce-fingerprinting) + - [Usar cookies de forma segura](#use-cookies-securely) + - [Não usar o nome padrão de cookie da sessão](#dont-use-the-default-session-cookie-name) + - [Definir opções de segurança de cookies](#set-cookie-security-options) + - [Impedir ataques brute-force contra a autorização](#prevent-brute-force-attacks-against-authorization) + - [Garanta que suas dependências sejam seguras](#ensure-your-dependencies-are-secure) + - [Evitar outras vulnerabilidades conhecidas](#avoid-other-known-vulnerabilities) + - [Considerações adicionais](#additional-considerations) ## Não usar versões obsoletas ou vulneráveis do Express @@ -44,7 +44,7 @@ Certifique-se também de que você não está usando nenhuma das versões vulner Se seu aplicativo lida com ou transmite dados confidenciais, use [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) para proteger a conexão e os dados. Esta tecnologia criptografa dados antes de ser enviada do cliente para o servidor, impedindo assim alguns hackers comuns (e fáceis). Embora solicitações do Ajax e POST não sejam óbvias e pareçam "ocultas" nos navegadores, seu tráfego de rede está vulnerável ao [sniffing de pacotes](https://en.wikipedia.org/wiki/Packet_analyzer) e [ataques do meio](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). -Você deve estar familiarizado com a criptografia Secure Socket Layer (SSL). [TLS é simplesmente a próxima progressão do SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). Em outras palavras, se você estava usando SSL antes, considere atualizar para o TLS. Em geral, recomendamos o Nginx para lidar com TLS. Para uma boa referência para configurar TLS no Nginx (e outros servidores), consulte [Configurações de servidores recomendadas (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). +Você deve estar familiarizado com a criptografia Secure Socket Layer (SSL). [TLS é simplesmente a próxima progressão do SSL](). Em outras palavras, se você estava usando SSL antes, considere atualizar para o TLS. Em geral, recomendamos o Nginx para lidar com TLS. Para uma boa referência para configurar TLS no Nginx (e outros servidores), consulte [Configurações de servidores recomendadas (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). Além disso, uma ferramenta prática para obter um certificado TLS gratuito é [Let's Encrypt](https://letsencrypt.org/about/), uma ferramenta gratuita, automatizada, e abrir autoridade certificadora (CA) fornecida pelo [Grupo de Investigação de Segurança da Internet (ISRG)](https://www.abetterinternet.org/). @@ -55,7 +55,7 @@ Em última análise, a responsabilidade de validar e manipular corretamente os t ### Impedir redirecionamentos abertos -Um exemplo de entrada de usuário potencialmente perigosa é um *open redirect*, onde um aplicativo aceita uma URL como entrada de usuário (muitas vezes na consulta de URL, por exemplo `? rl=https://exemplo. om`) e usa `res.redirect` para definir o cabeçalho `location` e +Um exemplo de entrada de usuário potencialmente perigosa é um _open redirect_, onde um aplicativo aceita uma URL como entrada de usuário (muitas vezes na consulta de URL, por exemplo `? rl=https://exemplo. om`) e usa `res.redirect` para definir o cabeçalho `location` e return um status de 3xx. Uma aplicação deve validar que suporta redirecionamento para a URL de entrada, para evitar enviar usuários para links maliciosos, como sites de phishing, entre outros riscos. @@ -81,19 +81,19 @@ app.use((req, res) => { Capacete é uma função middleware que define cabeçalhos de resposta HTTP relacionados à segurança. Capacete define os seguintes cabeçalhos por padrão: -* `Content-Security-Policy`: Uma poderosa lista de permissões do que pode acontecer na sua página, que mitiga muitos ataques -* `Cross-Origin-Opener-Policy`: Ajuda a isolar sua página -* `Cross-Origin-Resource-Policy`: Bloqueia outros de carregar seus recursos de cruzamento de origem -* `Origin-Agent-Cluster`: Altera o isolamento de processo para ser baseado na origem -* `Referrer-Policy`: Controla o cabeçalho [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) -* `Strict-Transport-Security`: Diz aos navegadores para preferirem HTTPS -* `X-Content-Type-Options`: Evitar [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) -* `X-DNS-Prefetch-Control`: Controls DNS prefetching -* `X-Download-Options`: Força os downloads a serem salvos (apenas no Internet Explorer -* `X-Frame-Options`: Cabeçalho de legado que mitiga [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) ataques -* `X-Perting-Cross-Domain-Policies`: Controla o comportamento entre domínios para produtos Adobe, como a Acrobat -* `X-Powered-By`: Informações sobre o servidor web. Removido porque poderia ser utilizado em ataques simples -* `X-XSS-Protection`: Cabeçalho de legado que tenta mitigar [ataques XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), mas piora as coisas, então o Capacete desabilita +- `Content-Security-Policy`: Uma poderosa lista de permissões do que pode acontecer na sua página, que mitiga muitos ataques +- `Cross-Origin-Opener-Policy`: Ajuda a isolar sua página +- `Cross-Origin-Resource-Policy`: Bloqueia outros de carregar seus recursos de cruzamento de origem +- `Origin-Agent-Cluster`: Altera o isolamento de processo para ser baseado na origem +- `Referrer-Policy`: Controla o cabeçalho [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) +- `Strict-Transport-Security`: Diz aos navegadores para preferirem HTTPS +- `X-Content-Type-Options`: Evitar [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +- `X-DNS-Prefetch-Control`: Controls DNS prefetching +- `X-Download-Options`: Força os downloads a serem salvos (apenas no Internet Explorer +- `X-Frame-Options`: Cabeçalho de legado que mitiga [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) ataques +- `X-Perting-Cross-Domain-Policies`: Controla o comportamento entre domínios para produtos Adobe, como a Acrobat +- `X-Powered-By`: Informações sobre o servidor web. Removido porque poderia ser utilizado em ataques simples +- `X-XSS-Protection`: Cabeçalho de legado que tenta mitigar [ataques XSS](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), mas piora as coisas, então o Capacete desabilita Cada cabeçalho pode ser configurado ou desativado. Para ler mais sobre isso, por favor, vá para [a documentação do site][helmet]. @@ -164,8 +164,8 @@ Para garantir que cookies não abram seu aplicativo para exploits, não use o no Existem dois principais módulos de sessão do cookie middleware: -* [express-session](https://www.npmjs.com/package/express-session) que substitui `express.session` middleware integrado ao Express 3.x. -* [cookie-session](https://www.npmjs.com/package/cookie-session) that replaces `express.cookieSession` middleware built-in to Express 3.x. +- [express-session](https://www.npmjs.com/package/express-session) que substitui `express.session` middleware integrado ao Express 3.x. +- [cookie-session](https://www.npmjs.com/package/cookie-session) that replaces `express.cookieSession` middleware built-in to Express 3.x. A principal diferença entre estes dois módulos é como eles salvam os dados da sessão de cookie. O [express-session](https://www.npmjs.com/package/express-session) middleware armazena os dados de sessão no servidor; apenas salva o ID da sessão no próprio cookie, não nos dados da sessão. Por padrão, ele usa armazenamento de memória e não é projetado para um ambiente de produção. Na produção, você precisará configurar uma loja de sessão escalável; ver a lista de [lojas de sessões compatíveis](https://github.com/expressjs/session#compatible-session-stores). @@ -192,11 +192,11 @@ app. se( Defina as seguintes opções de cookies para aumentar a segurança: -* `secure` - Garante que o navegador envie apenas o cookie via HTTPS. -* `httpOnly` - Garante que o cookie é enviado somente via HTTP(S), não do cliente JavaScript, ajudando a proteger contra ataques de script via site. -* `domínio` - indica o domínio do cookie; use-o para comparar com o domínio do servidor no qual a URL está sendo solicitada. Se eles coincidirem, verifique o atributo de caminho em seguida. -* `path` - indica o caminho do cookie; use-o para comparar com o caminho do pedido. Se este e o domínio corresponderem então envie o cookie na solicitação. -* `expires` - use para definir a data de validade para cookies persistentes. +- `secure` - Garante que o navegador envie apenas o cookie via HTTPS. +- `httpOnly` - Garante que o cookie é enviado somente via HTTP(S), não do cliente JavaScript, ajudando a proteger contra ataques de script via site. +- `domínio` - indica o domínio do cookie; use-o para comparar com o domínio do servidor no qual a URL está sendo solicitada. Se eles coincidirem, verifique o atributo de caminho em seguida. +- `path` - indica o caminho do cookie; use-o para comparar com o caminho do pedido. Se este e o domínio corresponderem então envie o cookie na solicitação. +- `expires` - use para definir a data de validade para cookies persistentes. Aqui está um exemplo usando [cookie-session](https://www.npmjs.com/package/cookie-session) middleware: @@ -267,10 +267,10 @@ Finalmente, Aplicativos Expressos—como qualquer outro aplicativo da web&md Aqui estão mais algumas recomendações do excelente [Checklist de Segurança do Node.js](https://blog.risingstack.com/node-js-security-checklist/). Consulte este post para todos os detalhes destas recomendações: -* Sempre filtre e sanize a entrada do usuário para proteger contra scripts entre sites (XSS) e ataques de injeção de comando. -* Defenda-se contra ataques de injeção de SQL usando consultas parametrizadas ou declarações preparadas. -* Use a ferramenta de código aberto [sqlmap](http://sqlmap.org/) para detectar as vulnerabilidades de injeção de SQL em seu aplicativo. -* Usar as ferramentas [nmap](https://nmap.org/) e [sslyze](https://github.com/nabla-c0d3/sslyze) para testar a configuração de suas cifras SSL, chaves e renegociação, bem como a validade de seu certificado. -* Use [safe-regex](https://www.npmjs.com/package/safe-regex) para garantir que suas expressões regulares não são suscetíveis a ataques [negação regular de serviço](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS). +- Sempre filtre e sanize a entrada do usuário para proteger contra scripts entre sites (XSS) e ataques de injeção de comando. +- Defenda-se contra ataques de injeção de SQL usando consultas parametrizadas ou declarações preparadas. +- Use a ferramenta de código aberto [sqlmap](http://sqlmap.org/) para detectar as vulnerabilidades de injeção de SQL em seu aplicativo. +- Usar as ferramentas [nmap](https://nmap.org/) e [sslyze](https://github.com/nabla-c0d3/sslyze) para testar a configuração de suas cifras SSL, chaves e renegociação, bem como a validade de seu certificado. +- Use [safe-regex](https://www.npmjs.com/package/safe-regex) para garantir que suas expressões regulares não são suscetíveis a ataques [negação regular de serviço](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS). [helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/pt-br/advanced/security-updates.mdx b/src/content/pages/pt-br/advanced/security-updates.mdx index 4920c9022f..38498582a3 100644 --- a/src/content/pages/pt-br/advanced/security-updates.mdx +++ b/src/content/pages/pt-br/advanced/security-updates.mdx @@ -24,42 +24,42 @@ Políticas e Procedimentos. ## 4.x -* 4.21.2 - * A dependência `path-to-regexp` foi atualizada para o endereço de um [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). -* 4.21.1 - * A dependência `cookie` foi atualizada para o endereço [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), isso pode afetar sua aplicação se você usar `res.cookie`. -* 4.20.0 - * Vulnerabilidade XSS corrigida em `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). - * A dependência `serve-static` foi atualizada para o endereço [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). - * A dependência `enviar` foi atualizada para o endereço [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). - * A dependência `path-to-regexp` foi atualizada para o endereço de um [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). - * A dependência `body-parser` foi atualizada para adicionar um [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), isso pode afetar sua aplicação se você tiver uma url ativa de codificação. -* 4.19.0, 4.19.1 - * Corrigido a vulnerabilidade de redirecionamento aberto em `res.location` e `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). -* 4.17.3 - * A dependência `qs` foi atualizada para o endereço [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). Isso pode afetar sua aplicação se as seguintes APIs forem usadas: `req.query`, `req.body`, `req.param`. -* 4.16.0 - * A dependência `encaminhado` foi atualizada para o endereço [vulnerability](https://npmjs.com/advisories/527). Isso pode afetar sua aplicação se as seguintes APIs forem usadas: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. - * A dependência `mime` foi atualizada para endereçar um [vulnerability](https://npmjs.com/advisories/535), mas esta issue não afeta o Express. - * A dependência `send` foi atualizada para fornecer uma proteção contra uma [Node.js 8.5.0 vulnerabilidade](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). Isso só afeta a execução do Express na versão 8.5.0 específica do Node.js. -* 4.15.5 - * A dependência `debug` foi atualizada para endereçar um [vulnerability](https://snyk.io/vuln/npm:debug:20170905), mas esta issue não afeta o Express. - * A dependência `fresh` foi atualizada para endereço [vulnerability](https://npmjs.com/advisories/526). Isso afetará sua aplicação se as seguintes APIs forem usadas: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendFile`, `res.sendStatus`. -* 4.15.3 - * A dependência `ms` foi atualizada para endereço [vulnerability](https://snyk.io/vuln/npm:ms:20170412). Isso pode afetar sua aplicação se entrada de string não confiável for passada para a opção `maxAge` nas seguintes APIs: `express.static`, `res.sendfile` e `res.sendFile`. -* 4.15.2 - * A dependência `qs` foi atualizada para endereçar um [vulnerability](https://snyk.io/vuln/npm:qs:20170213), mas esta issue não afeta o Express. Atualizar para 4.15.2 é uma boa prática, mas não é necessário para resolver a vulnerabilidade. -* 4.11.1 - * vulnerabilidade de divulgação de caminhos raiz corrigidos em `express.static`, `res.sendfile`, e `res.sendFile` -* 4.10.7 - * Corrigido a vulnerabilidade de redirecionamento aberto em `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 4.8.8 - * Vulnerabilidades de travessia de diretório fixas em `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). -* 4.8.4 - * Node.js 0.10 pode vazar `fd`s em certas situações que afetam `express.static` e `res.sendfile`. Solicitações maliciosas podem causar vazamento de `fd`s e eventualmente levar a erros `EMFILE` e servidor sem resposta. -* 4.8.0 - * Matrizes Sparse que possuem índices extremamente altos na cadeia de consulta pode fazer com que o processo fique sem memória e falhe o servidor. - * Objetos de string de consulta extremamente aninhados poderiam fazer com que o processo bloqueasse e tornar o servidor temporariamente não responsivo. +- 4.21.2 + - A dependência `path-to-regexp` foi atualizada para o endereço de um [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +- 4.21.1 + - A dependência `cookie` foi atualizada para o endereço [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), isso pode afetar sua aplicação se você usar `res.cookie`. +- 4.20.0 + - Vulnerabilidade XSS corrigida em `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + - A dependência `serve-static` foi atualizada para o endereço [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). + - A dependência `enviar` foi atualizada para o endereço [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + - A dependência `path-to-regexp` foi atualizada para o endereço de um [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + - A dependência `body-parser` foi atualizada para adicionar um [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), isso pode afetar sua aplicação se você tiver uma url ativa de codificação. +- 4.19.0, 4.19.1 + - Corrigido a vulnerabilidade de redirecionamento aberto em `res.location` e `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +- 4.17.3 + - A dependência `qs` foi atualizada para o endereço [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). Isso pode afetar sua aplicação se as seguintes APIs forem usadas: `req.query`, `req.body`, `req.param`. +- 4.16.0 + - A dependência `encaminhado` foi atualizada para o endereço [vulnerability](https://npmjs.com/advisories/527). Isso pode afetar sua aplicação se as seguintes APIs forem usadas: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + - A dependência `mime` foi atualizada para endereçar um [vulnerability](https://npmjs.com/advisories/535), mas esta issue não afeta o Express. + - A dependência `send` foi atualizada para fornecer uma proteção contra uma [Node.js 8.5.0 vulnerabilidade](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). Isso só afeta a execução do Express na versão 8.5.0 específica do Node.js. +- 4.15.5 + - A dependência `debug` foi atualizada para endereçar um [vulnerability](https://snyk.io/vuln/npm:debug:20170905), mas esta issue não afeta o Express. + - A dependência `fresh` foi atualizada para endereço [vulnerability](https://npmjs.com/advisories/526). Isso afetará sua aplicação se as seguintes APIs forem usadas: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendFile`, `res.sendStatus`. +- 4.15.3 + - A dependência `ms` foi atualizada para endereço [vulnerability](https://snyk.io/vuln/npm:ms:20170412). Isso pode afetar sua aplicação se entrada de string não confiável for passada para a opção `maxAge` nas seguintes APIs: `express.static`, `res.sendfile` e `res.sendFile`. +- 4.15.2 + - A dependência `qs` foi atualizada para endereçar um [vulnerability](https://snyk.io/vuln/npm:qs:20170213), mas esta issue não afeta o Express. Atualizar para 4.15.2 é uma boa prática, mas não é necessário para resolver a vulnerabilidade. +- 4.11.1 + - vulnerabilidade de divulgação de caminhos raiz corrigidos em `express.static`, `res.sendfile`, e `res.sendFile` +- 4.10.7 + - Corrigido a vulnerabilidade de redirecionamento aberto em `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 4.8.8 + - Vulnerabilidades de travessia de diretório fixas em `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +- 4.8.4 + - Node.js 0.10 pode vazar `fd`s em certas situações que afetam `express.static` e `res.sendfile`. Solicitações maliciosas podem causar vazamento de `fd`s e eventualmente levar a erros `EMFILE` e servidor sem resposta. +- 4.8.0 + - Matrizes Sparse que possuem índices extremamente altos na cadeia de consulta pode fazer com que o processo fique sem memória e falhe o servidor. + - Objetos de string de consulta extremamente aninhados poderiam fazer com que o processo bloqueasse e tornar o servidor temporariamente não responsivo. ## 3.x @@ -72,16 +72,16 @@ Se você não puder atualizar as anteriores 3.x, considere as [Opções de Supor -* 3.19.1 - * vulnerabilidade de divulgação de caminhos raiz corrigidos em `express.static`, `res.sendfile`, e `res.sendFile` -* 3.19.0 - * Corrigido a vulnerabilidade de redirecionamento aberto em `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 3.16.10 - * Vulnerabilidades de transposição de diretório fixas em `express.static`. -* 3.16.6 - * Node.js 0.10 pode vazar `fd`s em certas situações que afetam `express.static` e `res.sendfile`. Solicitações maliciosas podem causar vazamento de `fd`s e eventualmente levar a erros `EMFILE` e servidor sem resposta. -* 3.16.0 - * Matrizes Sparse que possuem índices extremamente altos em cadeia de consulta pode fazer com que o processo fique sem memória e falhe o servidor. - * Objetos de string de consulta extremamente aninhados poderiam fazer com que o processo bloqueasse e tornar o servidor temporariamente não responsivo. -* 3.3.0 - * A resposta 404 de uma tentativa de substituição de método não suportado era suscetível a ataques de script entre sites. +- 3.19.1 + - vulnerabilidade de divulgação de caminhos raiz corrigidos em `express.static`, `res.sendfile`, e `res.sendFile` +- 3.19.0 + - Corrigido a vulnerabilidade de redirecionamento aberto em `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 3.16.10 + - Vulnerabilidades de transposição de diretório fixas em `express.static`. +- 3.16.6 + - Node.js 0.10 pode vazar `fd`s em certas situações que afetam `express.static` e `res.sendfile`. Solicitações maliciosas podem causar vazamento de `fd`s e eventualmente levar a erros `EMFILE` e servidor sem resposta. +- 3.16.0 + - Matrizes Sparse que possuem índices extremamente altos em cadeia de consulta pode fazer com que o processo fique sem memória e falhe o servidor. + - Objetos de string de consulta extremamente aninhados poderiam fazer com que o processo bloqueasse e tornar o servidor temporariamente não responsivo. +- 3.3.0 + - A resposta 404 de uma tentativa de substituição de método não suportado era suscetível a ataques de script entre sites. diff --git a/src/content/pages/pt-br/guide/database-integration.mdx b/src/content/pages/pt-br/guide/database-integration.mdx index ef5e65beff..5d2de4370e 100644 --- a/src/content/pages/pt-br/guide/database-integration.mdx +++ b/src/content/pages/pt-br/guide/database-integration.mdx @@ -7,19 +7,19 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Adicionar a capacidade de conectar bancos de dados aos aplicativos Express é apenas uma questão de carregar um driver Node.js apropriado para o banco de dados em seu aplicativo. Este documento explica brevemente como adicionar e usar alguns dos mais populares módulos Node.js para os sistemas de banco de dados no seu aplicativo Express: -* [Cassandra](#cassandra) -* [Couchbase](#couchbase) -* [CouchDB](#couchdb) -* [LevelDB](#leveldb) -* [MySQL](#mysql) -* [MongoDB](#mongodb) -* [Neo4j](#neo4j) -* [Oracle](#oracle) -* [PostgreSQL](#postgresql) -* [Redis](#redis) -* [SQL Server](#sql-server) -* [SQLite](#sqlite) -* [Elasticsearch](#elasticsearch) +- [Cassandra](#cassandra) +- [Couchbase](#couchbase) +- [CouchDB](#couchdb) +- [LevelDB](#leveldb) +- [MySQL](#mysql) +- [MongoDB](#mongodb) +- [Neo4j](#neo4j) +- [Oracle](#oracle) +- [PostgreSQL](#postgresql) +- [Redis](#redis) +- [SQL Server](#sql-server) +- [SQLite](#sqlite) +- [Elasticsearch](#elasticsearch) @@ -44,7 +44,7 @@ $ npm install cassandra-driver const cassandra = require('cassandra-driver'); const client = new cassandra.Client({ contactPoints: ['localhost'] }); -cliente. xecute('selecione chave de system.local', (err, result) => { +cliente.xecute('selecione chave de system.local', (err, result) => { if (err) throw err; console.log(result.rows[0]); }); @@ -102,21 +102,21 @@ $ npm install nano ```js const nano = require('nano')('http://localhost:5984'); nano.db.create('books'); -const books = nano.db. se('livros'); +const books = nano.db.se('livros'); // Insira um documento de livro no banco de dados de livros -livros. nsert({ name: 'A Arte da guerra' }, null, (err, body) => { +livros.nsert({ name: 'A Arte da guerra' }, null, (err, body) => { if (err) { - console. og(err); + console.og(err); } else { - console. og(corpo); + console.og(corpo); } }); // Pegue uma lista de todos os livros -livros. ist((err, corpo) => { +livros.ist((err, corpo) => { if (err) { - console. og(err); + console.og(err); } else { console.log(body.rows); } @@ -192,7 +192,7 @@ connection.end(); $ npm install mongodb ``` -### Exemplo (v2.*) +### Exemplo (v2.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -200,17 +200,17 @@ const MongoClient = require('mongodb').MongoClient; MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { if (err) throw err; - db. ollection('mammal') + db.ollection('mammal') .find() - . oArray((err, result) => { + .oArray((err, result) => { if (err) throw err; - console. og(resultado); + console.og(resultado); }); }); ``` -### Exemplo (v3.*) +### Exemplo (v3.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -218,14 +218,14 @@ const MongoClient = require('mongodb').MongoClient; MongoClient.connect('mongodb://localhost:27017/animals', (err, client) => { if (err) throw err; - const db = client. b('animais'); + const db = client.b('animais'); db.collection('mammals') .find() - . oArray((err, result) => { + .oArray((err, result) => { if (err) throw err; - console. og(resultado); + console.og(resultado); }); }); ``` @@ -246,18 +246,18 @@ $ npm install neo4j-driver ```js const neo4j = require('neo4j-driver'); -const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth. asic('neo4j', 'letmein')); +const driver = neo4j.driver('neo4j://localhost:7687', neo4j.auth.asic('neo4j', 'letmein')); const session = driver.session(); session.readTransaction((tx) => { return tx - . un('MATCH (n) contagem RETURN COMO count') + .un('MATCH (n) contagem RETURN COMO count') .then((res) => { - console.log(res.records[0]. et('count')); + console.log(res.records[0].et('count')); }) .catch((error) => { - console. og(erro); + console.og(erro); }); }); ``` @@ -323,12 +323,12 @@ const pgp = require('pg-promise')(/* opções */); const db = pgp('postgres://username:password@host:port/database'); db.one('SELECT $1 AS valor', 123) - . hen((data) => { + .hen((data) => { console.log('DATA:', data.value); }) - . atch((error) => { + .atch((error) => { console.log('ERROR:', error); -}); + }); ``` ## Redis @@ -351,15 +351,15 @@ client.on('error', (err) => { console.log(`Error ${err}`); }); -cliente. et('string key', 'string val', redis.print); +cliente.et('string key', 'string val', redis.print); client.hset('hash key', 'hashtest 1', 'some value', redis.print); -cliente. set(['chave hash', 'hashtest 2', 'alguns outros valor'], redis.print); +cliente.set(['chave hash', 'hashtest 2', 'alguns outros valor'], redis.print); -cliente. keys('hash key', (err, respostas) => { +cliente.keys('hash key', (err, respostas) => { console.log(`${replies.length} respostas:`); - respostas. orEach((reply, i) => { - console. og(` ${i}: ${reply}`); + respostas.orEach((reply, i) => { + console.og(` ${i}: ${reply}`); }); cliente.quit(); @@ -480,7 +480,7 @@ const client = elasticsearch.Client({ }); client - . earch({ + .earch({ index: 'books', type: 'book', corpo: { @@ -492,12 +492,12 @@ client }, }, }) - . hen( + .hen( (resposta) => { - const hits = response.hits. itens; + const hits = response.hits.itens; }, (error) => { - console. race(error.message); + console.race(error.message); } -); + ); ``` diff --git a/src/content/pages/pt-br/guide/migrating-4.mdx b/src/content/pages/pt-br/guide/migrating-4.mdx index 086ca08ccc..196e881f52 100644 --- a/src/content/pages/pt-br/guide/migrating-4.mdx +++ b/src/content/pages/pt-br/guide/migrating-4.mdx @@ -40,8 +40,8 @@ Há várias mudanças significativas na Expresso 4: Ver também: -* [Novas funcionalidades em 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) -* [Migrando da 3.x para a versão 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) +- [Novas funcionalidades em 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +- [Migrando da 3.x para a versão 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) ### Alterações no núcleo do Express e sistema de middleware @@ -214,8 +214,8 @@ o middleware do `router`. A forma como você define rotas é inalterada, mas o sistema de roteamento tem dois novos recursos para ajudar a organizar suas rotas: -* Um novo método, `app.route()`, para criar gerenciadores de rotas em cadeia para um caminho de rota. -* Uma nova classe, `express.Router`, para criar modular montável handlers. +- Um novo método, `app.route()`, para criar gerenciadores de rotas em cadeia para um caminho de rota. +- Uma nova classe, `express.Router`, para criar modular montável handlers. #### Método `app.route()` @@ -229,14 +229,14 @@ Aqui está um exemplo de manipuladores de rota encadeados que são definidos usa app .route('/book') .get((req, res) => { - res. end('Recebe um livro aleatório'); + res.end('Recebe um livro aleatório'); }) - . ost((req, res) => { + .ost((req, res) => { res.send('Adicionar um livro'); }) - . ut((req, res) => { + .ut((req, res) => { res.send('Atualizar o livro'); -}); + }); ``` #### Classe `express.Router` @@ -298,7 +298,9 @@ A tabela a seguir lista outras pequenas mas importantes mudanças no Express 4: Node.js - Express 4 requer Node.js 0.10.x ou posterior e tem abandonado o suporte para Node.js 0.8. + + Express 4 requer Node.js 0.10.x ou posterior e tem abandonado o suporte para Node.js 0.8. + `http.createServer()` @@ -358,8 +360,8 @@ A tabela a seguir lista outras pequenas mas importantes mudanças no Express 4: `res.setHeader('Set-Cookie', val)` - A funcionalidade agora está limitada a definir o valor básico de cookie. Use `res.cookie()` para adicionar - funcionalidade. + A funcionalidade agora está limitada a definir o valor básico de cookie. Use `res.cookie()` + para adicionar funcionalidade. @@ -595,9 +597,9 @@ Express 4. Opções de comando e uso em grande parte permanecem iguais, com as seguintes exceções: -* A opção `--sessions` foi removida. -* A opção `--jshtml` foi removida. -* Adicionado a opção `--hogan` para apoiar [Hogan.js](http://twitter.github.io/hogan.js/). +- A opção `--sessions` foi removida. +- A opção `--jshtml` foi removida. +- Adicionado a opção `--hogan` para apoiar [Hogan.js](http://twitter.github.io/hogan.js/). ### Exemplo diff --git a/src/content/pages/pt-br/guide/migrating-5.mdx b/src/content/pages/pt-br/guide/migrating-5.mdx index 97c2021060..6236f46038 100644 --- a/src/content/pages/pt-br/guide/migrating-5.mdx +++ b/src/content/pages/pt-br/guide/migrating-5.mdx @@ -166,7 +166,7 @@ app.del('/user/:id', (req, res) => { }); // v5 -app. elete('/user/:id', (req, res) => { +app.elete('/user/:id', (req, res) => { res.send(`DELETE /user/${req.params.id}`); }); ``` @@ -198,14 +198,14 @@ npx codemod@latest @expressjs/pluralize-method-names // v4 app.all('/', (req, res) => { req.acceptsCharset('utf-8'); - req. cceptsEncoding('br'); + req.cceptsEncoding('br'); req.acceptsLanguage('en'); // ... }); // v5 -app. ll('/', (req, res) => { +app.ll('/', (req, res) => { req.acceptsCharsets('utf-8'); req.acceptsEncodings('br'); req.acceptsLanguages('en'); @@ -237,7 +237,7 @@ npx codemod@latest @expressjs/explicit-request-params // v4 app.post('/user', (req, res) => { const id = req.param('id'); - const body = req. aram('body'); + const body = req.aram('body'); const query = req.param('query'); // ... @@ -245,7 +245,7 @@ app.post('/user', (req, res) => { // v5 app.post('/user', (req, res) => { - const id = req.params. d; + const id = req.params.d; const body = req.body; const query = req.query; @@ -273,7 +273,7 @@ app.post('/user', (req, res) => { }); // v5 -aplicativo. ost('/user', (req, res) => { +aplicativo.ost('/user', (req, res) => { res.status(201).json({ name: 'Ruben' }); }); ``` @@ -323,7 +323,7 @@ app.get('/user', (req, res) => { }); // v5 -app. et('/user', (req, res) => { +app.et('/user', (req, res) => { res.redirect(301, '/users'); }); ``` @@ -373,7 +373,7 @@ app.get('/user', (req, res) => { }); // v5 -app. et('/user', (req, res) => { +app.et('/user', (req, res) => { res.status(200).send({ name: 'Ruben' }); }); ``` @@ -410,12 +410,12 @@ A função `res.sendfile()` foi substituída por uma versão caída por camelo ` **Nota:** No Expresso 5, `res. endFile()` usa o pacote `mime-types` para detecção do tipo MIME que retorna valores diferentes de Content-Type que Expresso 4 para vários tipos de arquivo comuns: -* Arquivos JavaScript (.js): agora "text/javascript" ao invés de "application/javascript" -* Arquivos JSON (.json): agora "application/json" em vez de "text/json" -* Arquivos CSS (.css): agora "text/css" em vez de "text/plain" -* Arquivos XML (.xml): agora "application/xml" em vez de "text/xml" -* Arquivos de fonte (.woff): agora "font/woff" em vez de "application/font-woff" -* Arquivos SVG (.svg): agora "image/svg+xml" em vez de "application/svg+xml" +- Arquivos JavaScript (.js): agora "text/javascript" ao invés de "application/javascript" +- Arquivos JSON (.json): agora "application/json" em vez de "text/json" +- Arquivos CSS (.css): agora "text/css" em vez de "text/plain" +- Arquivos XML (.xml): agora "application/xml" em vez de "text/xml" +- Arquivos de fonte (.woff): agora "font/woff" em vez de "application/font-woff" +- Arquivos SVG (.svg): agora "image/svg+xml" em vez de "application/svg+xml" Você pode substituir as assinaturas obsoletas pelo seguinte comando: @@ -449,12 +449,12 @@ Use o [pacote `mime-types`](https://github.com/jshttp/mime-types) para trabalhar **Importante:** Esta alteração afeta não apenas o uso direto de `express.static.mime`, mas também outros métodos Express que dependem da detecção de tipo MIME como `res.sendFile()`. Os seguintes tipos MIME mudaram de Express 4: -* Arquivos JavaScript (.js): agora servido como "text/javascript" em vez de "application/javascript" -* Arquivos JSON (.json): agora servido como "application/json" em vez de "text/json" -* Arquivos CSS (.css): agora servido como "text/css" em vez de "text/plain" -* Arquivos HTML (): agora servido como "text/html; charset=utf-8" ao invés de apenas "text/html" -* Arquivos XML (.xml): agora servido como "application/xml" ao invés de "text/xml" -* Arquivos de fonte (.woff): agora servido como "font/woff" em vez de "application/font-woff" +- Arquivos JavaScript (.js): agora servido como "text/javascript" em vez de "application/javascript" +- Arquivos JSON (.json): agora servido como "application/json" em vez de "text/json" +- Arquivos CSS (.css): agora servido como "text/css" em vez de "text/plain" +- Arquivos HTML (): agora servido como "text/html; charset=utf-8" ao invés de apenas "text/html" +- Arquivos XML (.xml): agora servido como "application/xml" ao invés de "text/xml" +- Arquivos de fonte (.woff): agora servido como "font/woff" em vez de "application/font-woff" ```js // v4 @@ -490,7 +490,7 @@ DEBUG=express:*,router,router:* node index.js A sintaxe de rota de correspondência de um caminho é quando uma string é fornecida como o primeiro parâmetro para o `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, and `router.use()` APIs. As seguintes alterações foram feitas em como a seqüência de caracteres de caminho é combinada para uma solicitação de entrada: -* O caractere curinga `*` deve ter um nome, correspondendo ao comportamento dos parâmetros `:`, use `/*splat` em vez de `/*` +- O caractere curinga `*` deve ter um nome, correspondendo ao comportamento dos parâmetros `:`, use `/*splat` em vez de `/*` ```js // v4 @@ -499,7 +499,7 @@ app.get('/*', async (req, res) => { }); // v5 -app. et('/*splat', async (req, res) => { +app.et('/*splat', async (req, res) => { res.send('ok'); }); ``` @@ -516,7 +516,7 @@ app.get('/{*splat}', async (req, res) => { -* O caractere opcional `?` não é mais suportado, use chaves em vez disso. +- O caractere opcional `?` não é mais suportado, use chaves em vez disso. ```js // v4 @@ -530,7 +530,7 @@ app.get('/:file{.:ext}', async (req, res) => { }); ``` -* Caracteres Regexp não são suportados. Por exemplo: +- Caracteres Regexp não são suportados. Por exemplo: ```js app.get('/[discussionőpage]/:slug', async (req, res) => { @@ -546,8 +546,8 @@ app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { }); ``` -* Alguns personagens foram reservados para evitar confusão durante a atualização (`()[]?+!`), use `\` para escapá-los. -* Os nomes de parâmetros agora suportam identificadores JavaScript válidos, ou citados como `:"isto"`. +- Alguns personagens foram reservados para evitar confusão durante a atualização (`()[]?+!`), use `\` para escapá-los. +- Os nomes de parâmetros agora suportam identificadores JavaScript válidos, ou citados como `:"isto"`. ### promessas rejeitadas tratadas de intermediários e manipuladores @@ -619,7 +619,7 @@ Caracteres curinga (por exemplo, `/*splat`) capturam segmentos de caminho como u ```js app.get('/*splat', (req, res) => { // GET /foo/bar - console.dir(req. arams); + console.dir(req.arams); // => [Objeto: null prototype] { splat: [ 'foo', 'bar' ] } }); ``` @@ -632,21 +632,21 @@ No Expresso 4, os caracteres curinga eram strings vazias (`''`) e parâmetros op // v4: curinga sem comparação é uma string vazia app.get('/*', (req, res) => { // GET / - console.dir(req. arams); + console.dir(req.arams); // => { '0': '' } }); // v4: parâmetro opcional não correspondente é indefinido -aplicativo. et('/:file.:ext?', (req, res) => { +aplicativo.et('/:file.:ext?', (req, res) => { // GET /image - console. ir(req.params); + console.ir(req.params); // => { file: 'image', ext: undefined } }); // v5: param opcional não comparado é omitido app.get('/:file{. ext}', (req, res) => { // GET /image - console.dir(req. arams); + console.dir(req.arams); // => [Object: null prototype] { file: 'image' } }); ``` diff --git a/src/content/pages/pt-br/resources/glossary.mdx b/src/content/pages/pt-br/resources/glossary.mdx index 0a5089e6d3..f0572e24fe 100644 --- a/src/content/pages/pt-br/resources/glossary.mdx +++ b/src/content/pages/pt-br/resources/glossary.mdx @@ -25,9 +25,9 @@ Uma biblioteca de suporte multiplataforma focada em E/O assíncrono, desenvolvid Uma função que é invocada pela camada de roteamento Express antes do manipulador de requisições final, e assim situa-se no meio entre um pedido em bruto e a rota final pretendida. Alguns belos pontos de terminologia em torno do middleware: -* `var foo = require('middleware')` é chamado de *requiring* ou *usando* um módulo Node.js. Então, a instrução `var mw = foo()` normalmente retorna o middleware. -* `app.use(mw)` é chamado de *adicionando o middleware à pilha de processamento global*. -* `app.get('/foo', mw, função (req, res) { ... })` é chamado de *adicionando o middleware para a pilha de processamento "GET /foo"*. +- `var foo = require('middleware')` é chamado de _requiring_ ou _usando_ um módulo Node.js. Então, a instrução `var mw = foo()` normalmente retorna o middleware. +- `app.use(mw)` é chamado de _adicionando o middleware à pilha de processamento global_. +- `app.get('/foo', mw, função (req, res) { ... })` é chamado de _adicionando o middleware para a pilha de processamento "GET /foo"_. ### Node.js diff --git a/src/content/pages/pt-br/resources/utils.md b/src/content/pages/pt-br/resources/utils.md index 51999b62f0..7bcafd69dd 100644 --- a/src/content/pages/pt-br/resources/utils.md +++ b/src/content/pages/pt-br/resources/utils.md @@ -8,15 +8,15 @@ description: Descubra módulos de utilitários relacionados ao Express.js e Node A organização [pillarjs](https://github.com/pillarjs) do GitHub contém um número de módulos para funções utilitárias que podem ser úteis em geral. -| Módulos utilitários | Descrição: | -| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Módulos utilitários | Descrição: | +| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [cookies](https://www.npmjs.com/package/cookies) | Obter e definir cookies HTTP(S) que podem ser assinados para evitar manipulação, usando Keygrip. Pode ser usado com a biblioteca HTTP do Node.js ou como Express middleware. | -| [csrf](https://www.npmjs.com/package/csrf) | Contém a lógica por trás da criação e verificação de tokens CSRF. Use este módulo para criar um middleware de CSRF personalizado. | -| [finalhandler](https://www.npmjs.com/package/finalhandler) | Função a invocar como o passo final para responder a requisição HTTP. | -| [parseurl](https://www.npmjs.com/package/parseurl) | Analisar uma URL com cache. | -| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Transforme uma string de caminho estilo Express, como \`\`/user/:name\` em uma expressão regular. | -| [resolve-path](https://www.npmjs.com/package/resolve-path) | Resolve um caminho relativo contra um caminho raiz com validação. | -| [router](https://www.npmjs.com/package/router) | Roteador simples ao estilo de middleware. | -| [send](https://www.npmjs.com/package/send) | Biblioteca para streaming de arquivos como uma resposta HTTP, com suporte para respostas parciais (intervalos), negociação condicional-GET e eventos granulares. | +| [csrf](https://www.npmjs.com/package/csrf) | Contém a lógica por trás da criação e verificação de tokens CSRF. Use este módulo para criar um middleware de CSRF personalizado. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Função a invocar como o passo final para responder a requisição HTTP. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Analisar uma URL com cache. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Transforme uma string de caminho estilo Express, como \`\`/user/:name\` em uma expressão regular. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Resolve um caminho relativo contra um caminho raiz com validação. | +| [router](https://www.npmjs.com/package/router) | Roteador simples ao estilo de middleware. | +| [send](https://www.npmjs.com/package/send) | Biblioteca para streaming de arquivos como uma resposta HTTP, com suporte para respostas parciais (intervalos), negociação condicional-GET e eventos granulares. | Para módulos adicionais de baixo nível relacionados à HTTP, consulte [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/pt-br/support.md b/src/content/pages/pt-br/support.md index eac7160c46..3687ec8365 100644 --- a/src/content/pages/pt-br/support.md +++ b/src/content/pages/pt-br/support.md @@ -7,14 +7,14 @@ Somente a versão mais recente de qualquer linha de lançamento principal é sup Versões que são EOL (fim de vida) _pode_ receber atualizações de vulnerabilidades de segurança críticas, mas a equipe Express não oferece garantia e não planeja endereçar ou liberar correções para quaisquer problemas encontrados. -| Versão maior | Versão mínima do Node.js | Início Suporte | Término Suporte | -| ------------------------------------------- | ---------------------------------------- | ---------------- | ---------------- | -| [**v5.x**](/en/5x/api) | 18 | Setembro de 2024 | **em andamento** | -| [**v4.x**](/en/4x/api) | 0.10.0 | Abril de 2014 | **em andamento** | -| [**v3.x**](/en/3x/api) | 0.8.0 | Outubro de 2012 | Julho de 2015 | -| [**v2.x**](/2x/) | 0.4.1 | Março de 2011 | Julho de 2012 | -| **v1.x** | 0.2.0 | Dezembro de 2010 | Março de 2011 | -| **v0.14.x** | 0.1.98 | Dezembro de 2010 | Dezembro de 2010 | +| Versão maior | Versão mínima do Node.js | Início Suporte | Término Suporte | +| ---------------------- | ------------------------ | ---------------- | ---------------- | +| [**v5.x**](/en/5x/api) | 18 | Setembro de 2024 | **em andamento** | +| [**v4.x**](/en/4x/api) | 0.10.0 | Abril de 2014 | **em andamento** | +| [**v3.x**](/en/3x/api) | 0.8.0 | Outubro de 2012 | Julho de 2015 | +| [**v2.x**](/2x/) | 0.4.1 | Março de 2011 | Julho de 2012 | +| **v1.x** | 0.2.0 | Dezembro de 2010 | Março de 2011 | +| **v0.14.x** | 0.1.98 | Dezembro de 2010 | Dezembro de 2010 | ## Opções de Suporte Comercial diff --git a/src/content/pages/zh-tw/advanced/best-practice-security.mdx b/src/content/pages/zh-tw/advanced/best-practice-security.mdx index fa7b7622bb..4ca68c5122 100644 --- a/src/content/pages/zh-tw/advanced/best-practice-security.mdx +++ b/src/content/pages/zh-tw/advanced/best-practice-security.mdx @@ -1,11 +1,11 @@ --- -title: "Production Best Practices: Security" +title: 'Production Best Practices: Security' description: Discover crucial security best practices for Express apps in production, including using TLS, input validation, secure cookies, and preventing vulnerabilities. --- import Alert from '@components/primitives/Alert/Alert.astro'; -The term *"production"* refers to the stage in the software lifecycle when an application or API is generally available to its end-users or consumers. In contrast, in the *"development"* stage, you're still actively writing and testing code, and the application is not open to external access. The corresponding system environments are known as *production* and *development* environments, respectively. +The term _"production"_ refers to the stage in the software lifecycle when an application or API is generally available to its end-users or consumers. In contrast, in the _"development"_ stage, you're still actively writing and testing code, and the application is not open to external access. The corresponding system environments are known as _production_ and _development_ environments, respectively. Development and production environments are usually set up differently and have vastly different requirements. What's fine in development may not be acceptable in production. For example, in a development environment you may want verbose logging of errors for debugging, while the same behavior can become a security concern in a production environment. And in development, you don't need to worry about scalability, reliability, and performance, while those concerns become critical in production. @@ -18,21 +18,21 @@ Policies and Procedures. Security best practices for Express applications in production include: -* [Production Best Practices: Security](#production-best-practices-security) - * [Overview](#overview) - * [Don't use deprecated or vulnerable versions of Express](#dont-use-deprecated-or-vulnerable-versions-of-express) - * [Use TLS](#use-tls) - * [Do not trust user input](#do-not-trust-user-input) - * [Prevent open redirects](#prevent-open-redirects) - * [Use Helmet](#use-helmet) - * [Reduce fingerprinting](#reduce-fingerprinting) - * [Use cookies securely](#use-cookies-securely) - * [Don't use the default session cookie name](#dont-use-the-default-session-cookie-name) - * [Set cookie security options](#set-cookie-security-options) - * [Prevent brute-force attacks against authorization](#prevent-brute-force-attacks-against-authorization) - * [Ensure your dependencies are secure](#ensure-your-dependencies-are-secure) - * [Avoid other known vulnerabilities](#avoid-other-known-vulnerabilities) - * [Additional considerations](#additional-considerations) +- [Production Best Practices: Security](#production-best-practices-security) + - [Overview](#overview) + - [Don't use deprecated or vulnerable versions of Express](#dont-use-deprecated-or-vulnerable-versions-of-express) + - [Use TLS](#use-tls) + - [Do not trust user input](#do-not-trust-user-input) + - [Prevent open redirects](#prevent-open-redirects) + - [Use Helmet](#use-helmet) + - [Reduce fingerprinting](#reduce-fingerprinting) + - [Use cookies securely](#use-cookies-securely) + - [Don't use the default session cookie name](#dont-use-the-default-session-cookie-name) + - [Set cookie security options](#set-cookie-security-options) + - [Prevent brute-force attacks against authorization](#prevent-brute-force-attacks-against-authorization) + - [Ensure your dependencies are secure](#ensure-your-dependencies-are-secure) + - [Avoid other known vulnerabilities](#avoid-other-known-vulnerabilities) + - [Additional considerations](#additional-considerations) ## Don't use deprecated or vulnerable versions of Express @@ -44,7 +44,7 @@ Also ensure you are not using any of the vulnerable Express versions listed on t If your app deals with or transmits sensitive data, use [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) (TLS) to secure the connection and the data. This technology encrypts data before it is sent from the client to the server, thus preventing some common (and easy) hacks. Although Ajax and POST requests might not be visibly obvious and seem "hidden" in browsers, their network traffic is vulnerable to [packet sniffing](https://en.wikipedia.org/wiki/Packet_analyzer) and [man-in-the-middle attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack). -You may be familiar with Secure Socket Layer (SSL) encryption. [TLS is simply the next progression of SSL](https://msdn.microsoft.com/en-us/library/windows/desktop/aa380515\(v=vs.85\).aspx). In other words, if you were using SSL before, consider upgrading to TLS. In general, we recommend Nginx to handle TLS. For a good reference to configure TLS on Nginx (and other servers), see [Recommended Server Configurations (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). +You may be familiar with Secure Socket Layer (SSL) encryption. [TLS is simply the next progression of SSL](). In other words, if you were using SSL before, consider upgrading to TLS. In general, we recommend Nginx to handle TLS. For a good reference to configure TLS on Nginx (and other servers), see [Recommended Server Configurations (Mozilla Wiki)](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_Server_Configurations). Also, a handy tool to get a free TLS certificate is [Let's Encrypt](https://letsencrypt.org/about/), a free, automated, and open certificate authority (CA) provided by the [Internet Security Research Group (ISRG)](https://www.abetterinternet.org/). @@ -55,7 +55,7 @@ Ultimately, the responsibility for validating and correctly handling the types o ### Prevent open redirects -An example of potentially dangerous user input is an *open redirect*, where an application accepts a URL as user input (often in the URL query, for example `?url=https://example.com`) and uses `res.redirect` to set the `location` header and +An example of potentially dangerous user input is an _open redirect_, where an application accepts a URL as user input (often in the URL query, for example `?url=https://example.com`) and uses `res.redirect` to set the `location` header and return a 3xx status. An application must validate that it supports redirecting to the incoming URL to avoid sending users to malicious links such as phishing websites, among other risks. @@ -81,19 +81,19 @@ app.use((req, res) => { Helmet is a middleware function that sets security-related HTTP response headers. Helmet sets the following headers by default: -* `Content-Security-Policy`: A powerful allow-list of what can happen on your page which mitigates many attacks -* `Cross-Origin-Opener-Policy`: Helps process-isolate your page -* `Cross-Origin-Resource-Policy`: Blocks others from loading your resources cross-origin -* `Origin-Agent-Cluster`: Changes process isolation to be origin-based -* `Referrer-Policy`: Controls the [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) header -* `Strict-Transport-Security`: Tells browsers to prefer HTTPS -* `X-Content-Type-Options`: Avoids [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) -* `X-DNS-Prefetch-Control`: Controls DNS prefetching -* `X-Download-Options`: Forces downloads to be saved (Internet Explorer only) -* `X-Frame-Options`: Legacy header that mitigates [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) attacks -* `X-Permitted-Cross-Domain-Policies`: Controls cross-domain behavior for Adobe products, like Acrobat -* `X-Powered-By`: Info about the web server. Removed because it could be used in simple attacks -* `X-XSS-Protection`: Legacy header that tries to mitigate [XSS attacks](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), but makes things worse, so Helmet disables it +- `Content-Security-Policy`: A powerful allow-list of what can happen on your page which mitigates many attacks +- `Cross-Origin-Opener-Policy`: Helps process-isolate your page +- `Cross-Origin-Resource-Policy`: Blocks others from loading your resources cross-origin +- `Origin-Agent-Cluster`: Changes process isolation to be origin-based +- `Referrer-Policy`: Controls the [`Referer`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referer) header +- `Strict-Transport-Security`: Tells browsers to prefer HTTPS +- `X-Content-Type-Options`: Avoids [MIME sniffing](https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types#mime_sniffing) +- `X-DNS-Prefetch-Control`: Controls DNS prefetching +- `X-Download-Options`: Forces downloads to be saved (Internet Explorer only) +- `X-Frame-Options`: Legacy header that mitigates [Clickjacking](https://en.wikipedia.org/wiki/Clickjacking) attacks +- `X-Permitted-Cross-Domain-Policies`: Controls cross-domain behavior for Adobe products, like Acrobat +- `X-Powered-By`: Info about the web server. Removed because it could be used in simple attacks +- `X-XSS-Protection`: Legacy header that tries to mitigate [XSS attacks](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), but makes things worse, so Helmet disables it Each header can be configured or disabled. To read more about it please go to [its documentation website][helmet]. @@ -164,8 +164,8 @@ To ensure cookies don't open your app to exploits, don't use the default session There are two main middleware cookie session modules: -* [express-session](https://www.npmjs.com/package/express-session) that replaces `express.session` middleware built-in to Express 3.x. -* [cookie-session](https://www.npmjs.com/package/cookie-session) that replaces `express.cookieSession` middleware built-in to Express 3.x. +- [express-session](https://www.npmjs.com/package/express-session) that replaces `express.session` middleware built-in to Express 3.x. +- [cookie-session](https://www.npmjs.com/package/cookie-session) that replaces `express.cookieSession` middleware built-in to Express 3.x. The main difference between these two modules is how they save cookie session data. The [express-session](https://www.npmjs.com/package/express-session) middleware stores session data on the server; it only saves the session ID in the cookie itself, not session data. By default, it uses in-memory storage and is not designed for a production environment. In production, you'll need to set up a scalable session-store; see the list of [compatible session stores](https://github.com/expressjs/session#compatible-session-stores). @@ -192,11 +192,11 @@ app.use( Set the following cookie options to enhance security: -* `secure` - Ensures the browser only sends the cookie over HTTPS. -* `httpOnly` - Ensures the cookie is sent only over HTTP(S), not client JavaScript, helping to protect against cross-site scripting attacks. -* `domain` - indicates the domain of the cookie; use it to compare against the domain of the server in which the URL is being requested. If they match, then check the path attribute next. -* `path` - indicates the path of the cookie; use it to compare against the request path. If this and domain match, then send the cookie in the request. -* `expires` - use to set expiration date for persistent cookies. +- `secure` - Ensures the browser only sends the cookie over HTTPS. +- `httpOnly` - Ensures the cookie is sent only over HTTP(S), not client JavaScript, helping to protect against cross-site scripting attacks. +- `domain` - indicates the domain of the cookie; use it to compare against the domain of the server in which the URL is being requested. If they match, then check the path attribute next. +- `path` - indicates the path of the cookie; use it to compare against the request path. If this and domain match, then send the cookie in the request. +- `expires` - use to set expiration date for persistent cookies. Here is an example using [cookie-session](https://www.npmjs.com/package/cookie-session) middleware: @@ -267,10 +267,10 @@ Finally, Express apps—like any other web apps—can be vulnerable to a Here are some further recommendations from the excellent [Node.js Security Checklist](https://blog.risingstack.com/node-js-security-checklist/). Refer to that blog post for all the details on these recommendations: -* Always filter and sanitize user input to protect against cross-site scripting (XSS) and command injection attacks. -* Defend against SQL injection attacks by using parameterized queries or prepared statements. -* Use the open-source [sqlmap](http://sqlmap.org/) tool to detect SQL injection vulnerabilities in your app. -* Use the [nmap](https://nmap.org/) and [sslyze](https://github.com/nabla-c0d3/sslyze) tools to test the configuration of your SSL ciphers, keys, and renegotiation as well as the validity of your certificate. -* Use [safe-regex](https://www.npmjs.com/package/safe-regex) to ensure your regular expressions are not susceptible to [regular expression denial of service](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) attacks. +- Always filter and sanitize user input to protect against cross-site scripting (XSS) and command injection attacks. +- Defend against SQL injection attacks by using parameterized queries or prepared statements. +- Use the open-source [sqlmap](http://sqlmap.org/) tool to detect SQL injection vulnerabilities in your app. +- Use the [nmap](https://nmap.org/) and [sslyze](https://github.com/nabla-c0d3/sslyze) tools to test the configuration of your SSL ciphers, keys, and renegotiation as well as the validity of your certificate. +- Use [safe-regex](https://www.npmjs.com/package/safe-regex) to ensure your regular expressions are not susceptible to [regular expression denial of service](https://www.owasp.org/index.php/Regular_expression_Denial_of_Service_-_ReDoS) attacks. [helmet]: https://helmetjs.github.io/ diff --git a/src/content/pages/zh-tw/advanced/security-updates.mdx b/src/content/pages/zh-tw/advanced/security-updates.mdx index dfed519ec6..c5ea3f336a 100644 --- a/src/content/pages/zh-tw/advanced/security-updates.mdx +++ b/src/content/pages/zh-tw/advanced/security-updates.mdx @@ -24,42 +24,42 @@ Policies and Procedures. ## 4.x -* 4.21.2 - * The dependency `path-to-regexp` has been updated to address a [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). -* 4.21.1 - * The dependency `cookie` has been updated to address a [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), This may affect your application if you use `res.cookie`. -* 4.20.0 - * Fixed XSS vulnerability in `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). - * The dependency `serve-static` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). - * The dependency `send` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). - * The dependency `path-to-regexp` has been updated to address a [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). - * The dependency `body-parser` has been updated to addres a [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), This may affect your application if you had url enconding activated. -* 4.19.0, 4.19.1 - * Fixed open redirect vulnerability in `res.location` and `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). -* 4.17.3 - * The dependency `qs` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). This may affect your application if the following APIs are used: `req.query`, `req.body`, `req.param`. -* 4.16.0 - * The dependency `forwarded` has been updated to address a [vulnerability](https://npmjs.com/advisories/527). This may affect your application if the following APIs are used: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. - * The dependency `mime` has been updated to address a [vulnerability](https://npmjs.com/advisories/535), but this issue does not impact Express. - * The dependency `send` has been updated to provide a protection against a [Node.js 8.5.0 vulnerability](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). This only impacts running Express on the specific Node.js version 8.5.0. -* 4.15.5 - * The dependency `debug` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:debug:20170905), but this issue does not impact Express. - * The dependency `fresh` has been updated to address a [vulnerability](https://npmjs.com/advisories/526). This will affect your application if the following APIs are used: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. -* 4.15.3 - * The dependency `ms` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:ms:20170412). This may affect your application if untrusted string input is passed to the `maxAge` option in the following APIs: `express.static`, `res.sendfile`, and `res.sendFile`. -* 4.15.2 - * The dependency `qs` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:qs:20170213), but this issue does not impact Express. Updating to 4.15.2 is a good practice, but not required to address the vulnerability. -* 4.11.1 - * Fixed root path disclosure vulnerability in `express.static`, `res.sendfile`, and `res.sendFile` -* 4.10.7 - * Fixed open redirect vulnerability in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 4.8.8 - * Fixed directory traversal vulnerabilities in `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). -* 4.8.4 - * Node.js 0.10 can leak `fd`s in certain situations that affect `express.static` and `res.sendfile`. Malicious requests could cause `fd`s to leak and eventually lead to `EMFILE` errors and server unresponsiveness. -* 4.8.0 - * Sparse arrays that have extremely high indexes in the query string could cause the process to run out of memory and crash the server. - * Extremely nested query string objects could cause the process to block and make the server unresponsive temporarily. +- 4.21.2 + - The dependency `path-to-regexp` has been updated to address a [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-rhx6-c78j-4q9w). +- 4.21.1 + - The dependency `cookie` has been updated to address a [vulnerability](https://github.com/jshttp/cookie/security/advisories/GHSA-pxg6-pf52-xh8x), This may affect your application if you use `res.cookie`. +- 4.20.0 + - Fixed XSS vulnerability in `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-qw6h-vgh9-j6wx), [CVE-2024-43796](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-43796)). + - The dependency `serve-static` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-cm22-4g7w-348p). + - The dependency `send` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-m6fv-jmcg-4jfg). + - The dependency `path-to-regexp` has been updated to address a [vulnerability](https://github.com/pillarjs/path-to-regexp/security/advisories/GHSA-9wv6-86v2-598j). + - The dependency `body-parser` has been updated to addres a [vulnerability](https://github.com/advisories/GHSA-qwcr-r2fm-qrc7), This may affect your application if you had url enconding activated. +- 4.19.0, 4.19.1 + - Fixed open redirect vulnerability in `res.location` and `res.redirect` ([advisory](https://github.com/expressjs/express/security/advisories/GHSA-rv95-896h-c2vc), [CVE-2024-29041](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-29041)). +- 4.17.3 + - The dependency `qs` has been updated to address a [vulnerability](https://github.com/advisories/GHSA-hrpp-h998-j3pp). This may affect your application if the following APIs are used: `req.query`, `req.body`, `req.param`. +- 4.16.0 + - The dependency `forwarded` has been updated to address a [vulnerability](https://npmjs.com/advisories/527). This may affect your application if the following APIs are used: `req.host`, `req.hostname`, `req.ip`, `req.ips`, `req.protocol`. + - The dependency `mime` has been updated to address a [vulnerability](https://npmjs.com/advisories/535), but this issue does not impact Express. + - The dependency `send` has been updated to provide a protection against a [Node.js 8.5.0 vulnerability](https://nodejs.org/en/blog/vulnerability/september-2017-path-validation/). This only impacts running Express on the specific Node.js version 8.5.0. +- 4.15.5 + - The dependency `debug` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:debug:20170905), but this issue does not impact Express. + - The dependency `fresh` has been updated to address a [vulnerability](https://npmjs.com/advisories/526). This will affect your application if the following APIs are used: `express.static`, `req.fresh`, `res.json`, `res.jsonp`, `res.send`, `res.sendfile` `res.sendFile`, `res.sendStatus`. +- 4.15.3 + - The dependency `ms` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:ms:20170412). This may affect your application if untrusted string input is passed to the `maxAge` option in the following APIs: `express.static`, `res.sendfile`, and `res.sendFile`. +- 4.15.2 + - The dependency `qs` has been updated to address a [vulnerability](https://snyk.io/vuln/npm:qs:20170213), but this issue does not impact Express. Updating to 4.15.2 is a good practice, but not required to address the vulnerability. +- 4.11.1 + - Fixed root path disclosure vulnerability in `express.static`, `res.sendfile`, and `res.sendFile` +- 4.10.7 + - Fixed open redirect vulnerability in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 4.8.8 + - Fixed directory traversal vulnerabilities in `express.static` ([advisory](http://npmjs.com/advisories/32) , [CVE-2014-6394](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-6394)). +- 4.8.4 + - Node.js 0.10 can leak `fd`s in certain situations that affect `express.static` and `res.sendfile`. Malicious requests could cause `fd`s to leak and eventually lead to `EMFILE` errors and server unresponsiveness. +- 4.8.0 + - Sparse arrays that have extremely high indexes in the query string could cause the process to run out of memory and crash the server. + - Extremely nested query string objects could cause the process to block and make the server unresponsive temporarily. ## 3.x @@ -72,16 +72,16 @@ If you are unable to upgrade past 3.x, please consider [Commercial Support Optio -* 3.19.1 - * Fixed root path disclosure vulnerability in `express.static`, `res.sendfile`, and `res.sendFile` -* 3.19.0 - * Fixed open redirect vulnerability in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). -* 3.16.10 - * Fixed directory traversal vulnerabilities in `express.static`. -* 3.16.6 - * Node.js 0.10 can leak `fd`s in certain situations that affect `express.static` and `res.sendfile`. Malicious requests could cause `fd`s to leak and eventually lead to `EMFILE` errors and server unresponsiveness. -* 3.16.0 - * Sparse arrays that have extremely high indexes in query string could cause the process to run out of memory and crash the server. - * Extremely nested query string objects could cause the process to block and make the server unresponsive temporarily. -* 3.3.0 - * The 404 response of an unsupported method override attempt was susceptible to cross-site scripting attacks. +- 3.19.1 + - Fixed root path disclosure vulnerability in `express.static`, `res.sendfile`, and `res.sendFile` +- 3.19.0 + - Fixed open redirect vulnerability in `express.static` ([advisory](https://npmjs.com/advisories/35), [CVE-2015-1164](http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-1164)). +- 3.16.10 + - Fixed directory traversal vulnerabilities in `express.static`. +- 3.16.6 + - Node.js 0.10 can leak `fd`s in certain situations that affect `express.static` and `res.sendfile`. Malicious requests could cause `fd`s to leak and eventually lead to `EMFILE` errors and server unresponsiveness. +- 3.16.0 + - Sparse arrays that have extremely high indexes in query string could cause the process to run out of memory and crash the server. + - Extremely nested query string objects could cause the process to block and make the server unresponsive temporarily. +- 3.3.0 + - The 404 response of an unsupported method override attempt was susceptible to cross-site scripting attacks. diff --git a/src/content/pages/zh-tw/guide/database-integration.mdx b/src/content/pages/zh-tw/guide/database-integration.mdx index 9a97d66c47..b0855e4a2a 100644 --- a/src/content/pages/zh-tw/guide/database-integration.mdx +++ b/src/content/pages/zh-tw/guide/database-integration.mdx @@ -7,19 +7,19 @@ import Alert from '@components/primitives/Alert/Alert.astro'; Adding the capability to connect databases to Express apps is just a matter of loading an appropriate Node.js driver for the database in your app. This document briefly explains how to add and use some of the most popular Node.js modules for database systems in your Express app: -* [Cassandra](#cassandra) -* [Couchbase](#couchbase) -* [CouchDB](#couchdb) -* [LevelDB](#leveldb) -* [MySQL](#mysql) -* [MongoDB](#mongodb) -* [Neo4j](#neo4j) -* [Oracle](#oracle) -* [PostgreSQL](#postgresql) -* [Redis](#redis) -* [SQL Server](#sql-server) -* [SQLite](#sqlite) -* [Elasticsearch](#elasticsearch) +- [Cassandra](#cassandra) +- [Couchbase](#couchbase) +- [CouchDB](#couchdb) +- [LevelDB](#leveldb) +- [MySQL](#mysql) +- [MongoDB](#mongodb) +- [Neo4j](#neo4j) +- [Oracle](#oracle) +- [PostgreSQL](#postgresql) +- [Redis](#redis) +- [SQL Server](#sql-server) +- [SQLite](#sqlite) +- [Elasticsearch](#elasticsearch) @@ -192,7 +192,7 @@ connection.end(); $ npm install mongodb ``` -### Example (v2.*) +### Example (v2.\*) ```js const MongoClient = require('mongodb').MongoClient; @@ -210,7 +210,7 @@ MongoClient.connect('mongodb://localhost:27017/animals', (err, db) => { }); ``` -### Example (v3.*) +### Example (v3.\*) ```js const MongoClient = require('mongodb').MongoClient; diff --git a/src/content/pages/zh-tw/guide/migrating-4.mdx b/src/content/pages/zh-tw/guide/migrating-4.mdx index 619682818a..42a1b63163 100644 --- a/src/content/pages/zh-tw/guide/migrating-4.mdx +++ b/src/content/pages/zh-tw/guide/migrating-4.mdx @@ -5,7 +5,7 @@ description: A guide to migrating your Express.js applications from version 3 to import Alert from '@components/primitives/Alert/Alert.astro'; -Express 4 is a breaking change from Express 3. That means an existing Express 3 app will *not* work if you update the Express version in its dependencies. +Express 4 is a breaking change from Express 3. That means an existing Express 3 app will _not_ work if you update the Express version in its dependencies. This article covers: @@ -40,8 +40,8 @@ There are several significant changes in Express 4: See also: -* [New features in 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) -* [Migrating from 3.x to 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) +- [New features in 4.x.](https://github.com/expressjs/express/wiki/New-features-in-4.x) +- [Migrating from 3.x to 4.x.](https://github.com/expressjs/express/wiki/Migrating-from-3.x-to-4.x) ### Changes to Express core and middleware system @@ -214,8 +214,8 @@ the `router` middleware. The way you define routes is unchanged, but the routing system has two new features to help organize your routes: -* A new method, `app.route()`, to create chainable route handlers for a route path. -* A new class, `express.Router`, to create modular mountable route handlers. +- A new method, `app.route()`, to create chainable route handlers for a route path. +- A new class, `express.Router`, to create modular mountable route handlers. #### `app.route()` method @@ -595,9 +595,9 @@ Express 4 generator. Command options and use largely remain the same, with the following exceptions: -* Removed the `--sessions` option. -* Removed the `--jshtml` option. -* Added the `--hogan` option to support [Hogan.js](http://twitter.github.io/hogan.js/). +- Removed the `--sessions` option. +- Removed the `--jshtml` option. +- Added the `--hogan` option to support [Hogan.js](http://twitter.github.io/hogan.js/). ### Example diff --git a/src/content/pages/zh-tw/guide/migrating-5.mdx b/src/content/pages/zh-tw/guide/migrating-5.mdx index 2a035c4e04..dac703c953 100644 --- a/src/content/pages/zh-tw/guide/migrating-5.mdx +++ b/src/content/pages/zh-tw/guide/migrating-5.mdx @@ -410,12 +410,12 @@ The `res.sendfile()` function has been replaced by a camel-cased version `res.se **Note:** In Express 5, `res.sendFile()` uses the `mime-types` package for MIME type detection, which returns different Content-Type values than Express 4 for several common file types: -* JavaScript files (.js): now "text/javascript" instead of "application/javascript" -* JSON files (.json): now "application/json" instead of "text/json" -* CSS files (.css): now "text/css" instead of "text/plain" -* XML files (.xml): now "application/xml" instead of "text/xml" -* Font files (.woff): now "font/woff" instead of "application/font-woff" -* SVG files (.svg): now "image/svg+xml" instead of "application/svg+xml" +- JavaScript files (.js): now "text/javascript" instead of "application/javascript" +- JSON files (.json): now "application/json" instead of "text/json" +- CSS files (.css): now "text/css" instead of "text/plain" +- XML files (.xml): now "application/xml" instead of "text/xml" +- Font files (.woff): now "font/woff" instead of "application/font-woff" +- SVG files (.svg): now "image/svg+xml" instead of "application/svg+xml" You can replace the deprecated signatures with the following command: @@ -449,12 +449,12 @@ Use the [`mime-types` package](https://github.com/jshttp/mime-types) to work wit **Important:** This change affects not only direct usage of `express.static.mime` but also other Express methods that rely on MIME type detection, such as `res.sendFile()`. The following MIME types have changed from Express 4: -* JavaScript files (.js): now served as "text/javascript" instead of "application/javascript" -* JSON files (.json): now served as "application/json" instead of "text/json" -* CSS files (.css): now served as "text/css" instead of "text/plain" -* HTML files (): now served as "text/html; charset=utf-8" instead of just "text/html" -* XML files (.xml): now served as "application/xml" instead of "text/xml" -* Font files (.woff): now served as "font/woff" instead of "application/font-woff" +- JavaScript files (.js): now served as "text/javascript" instead of "application/javascript" +- JSON files (.json): now served as "application/json" instead of "text/json" +- CSS files (.css): now served as "text/css" instead of "text/plain" +- HTML files (): now served as "text/html; charset=utf-8" instead of just "text/html" +- XML files (.xml): now served as "application/xml" instead of "text/xml" +- Font files (.woff): now served as "font/woff" instead of "application/font-woff" ```js // v4 @@ -490,7 +490,7 @@ DEBUG=express:*,router,router:* node index.js Path route matching syntax is when a string is supplied as the first parameter to the `app.all()`, `app.use()`, `app.METHOD()`, `router.all()`, `router.METHOD()`, and `router.use()` APIs. The following changes have been made to how the path string is matched to an incoming request: -* The wildcard `*` must have a name, matching the behavior of parameters `:`, use `/*splat` instead of `/*` +- The wildcard `*` must have a name, matching the behavior of parameters `:`, use `/*splat` instead of `/*` ```js // v4 @@ -516,7 +516,7 @@ app.get('/{*splat}', async (req, res) => { -* The optional character `?` is no longer supported, use braces instead. +- The optional character `?` is no longer supported, use braces instead. ```js // v4 @@ -530,7 +530,7 @@ app.get('/:file{.:ext}', async (req, res) => { }); ``` -* Regexp characters are not supported. For example: +- Regexp characters are not supported. For example: ```js app.get('/[discussion|page]/:slug', async (req, res) => { @@ -546,8 +546,8 @@ app.get(['/discussion/:slug', '/page/:slug'], async (req, res) => { }); ``` -* Some characters have been reserved to avoid confusion during upgrade (`()[]?+!`), use `\` to escape them. -* Parameter names now support valid JavaScript identifiers, or quoted like `:"this"`. +- Some characters have been reserved to avoid confusion during upgrade (`()[]?+!`), use `\` to escape them. +- Parameter names now support valid JavaScript identifiers, or quoted like `:"this"`. ### Rejected promises handled from middleware and handlers diff --git a/src/content/pages/zh-tw/resources/glossary.mdx b/src/content/pages/zh-tw/resources/glossary.mdx index e94e59ab60..c40a0a2e15 100644 --- a/src/content/pages/zh-tw/resources/glossary.mdx +++ b/src/content/pages/zh-tw/resources/glossary.mdx @@ -25,9 +25,9 @@ A multi-platform support library which focuses on asynchronous I/O, primarily de A function that is invoked by the Express routing layer before the final request handler, and thus sits in the middle between a raw request and the final intended route. A few fine points of terminology around middleware: -* `var foo = require('middleware')` is called *requiring* or *using* a Node.js module. Then the statement `var mw = foo()` typically returns the middleware. -* `app.use(mw)` is called *adding the middleware to the global processing stack*. -* `app.get('/foo', mw, function (req, res) { ... })` is called *adding the middleware to the "GET /foo" processing stack*. +- `var foo = require('middleware')` is called _requiring_ or _using_ a Node.js module. Then the statement `var mw = foo()` typically returns the middleware. +- `app.use(mw)` is called _adding the middleware to the global processing stack_. +- `app.get('/foo', mw, function (req, res) { ... })` is called _adding the middleware to the "GET /foo" processing stack_. ### Node.js diff --git a/src/content/pages/zh-tw/resources/utils.md b/src/content/pages/zh-tw/resources/utils.md index 3a8b0a5be1..739b352f3e 100644 --- a/src/content/pages/zh-tw/resources/utils.md +++ b/src/content/pages/zh-tw/resources/utils.md @@ -8,15 +8,15 @@ description: Discover utility modules related to Express.js and Node.js, includi The [pillarjs](https://github.com/pillarjs) GitHub organization contains a number of modules for utility functions that may be generally useful. -| Utility modules | Description | -| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Utility modules | Description | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | [cookies](https://www.npmjs.com/package/cookies) | Get and set HTTP(S) cookies that can be signed to prevent tampering, using Keygrip. Can be used with the Node.js HTTP library or as Express middleware. | -| [csrf](https://www.npmjs.com/package/csrf) | Contains the logic behind CSRF token creation and verification. Use this module to create custom CSRF middleware. | -| [finalhandler](https://www.npmjs.com/package/finalhandler) | Function to invoke as the final step to respond to HTTP request. | -| [parseurl](https://www.npmjs.com/package/parseurl) | Parse a URL with caching. | -| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Turn an Express-style path string such as \`\`/user/:name\` into a regular expression. | -| [resolve-path](https://www.npmjs.com/package/resolve-path) | Resolves a relative path against a root path with validation. | -| [router](https://www.npmjs.com/package/router) | Simple middleware-style router. | -| [send](https://www.npmjs.com/package/send) | Library for streaming files as a HTTP response, with support for partial responses (ranges), conditional-GET negotiation, and granular events. | +| [csrf](https://www.npmjs.com/package/csrf) | Contains the logic behind CSRF token creation and verification. Use this module to create custom CSRF middleware. | +| [finalhandler](https://www.npmjs.com/package/finalhandler) | Function to invoke as the final step to respond to HTTP request. | +| [parseurl](https://www.npmjs.com/package/parseurl) | Parse a URL with caching. | +| [path-to-regexp](https://www.npmjs.com/package/path-to-regexp) | Turn an Express-style path string such as \`\`/user/:name\` into a regular expression. | +| [resolve-path](https://www.npmjs.com/package/resolve-path) | Resolves a relative path against a root path with validation. | +| [router](https://www.npmjs.com/package/router) | Simple middleware-style router. | +| [send](https://www.npmjs.com/package/send) | Library for streaming files as a HTTP response, with support for partial responses (ranges), conditional-GET negotiation, and granular events. | For additional low-level HTTP-related modules, see [jshttp](https://github.com/jshttp). diff --git a/src/content/pages/zh-tw/support.md b/src/content/pages/zh-tw/support.md index 68763b76f0..9e59b0976b 100644 --- a/src/content/pages/zh-tw/support.md +++ b/src/content/pages/zh-tw/support.md @@ -7,14 +7,14 @@ Only the latest version of any given major release line is supported. Versions that are EOL (end-of-life) _may_ receive updates for critical security vulnerabilities, but the Express team offers no guarantee and does not plan to address or release fixes for any issues found. -| Major Version | Minimum Node.js Version | Support Start Date | Support End Date | -| ------------------------------------------- | --------------------------------------- | ------------------ | ---------------- | -| [**v5.x**](/en/5x/api) | 18 | September 2024 | **ongoing** | -| [**v4.x**](/en/4x/api) | 0.10.0 | April 2014 | **ongoing** | -| [**v3.x**](/en/3x/api) | 0.8.0 | October 2012 | July 2015 | -| [**v2.x**](/2x/) | 0.4.1 | March 2011 | July 2012 | -| **v1.x** | 0.2.0 | December 2010 | March 2011 | -| **v0.14.x** | 0.1.98 | December 2010 | December 2010 | +| Major Version | Minimum Node.js Version | Support Start Date | Support End Date | +| ---------------------- | ----------------------- | ------------------ | ---------------- | +| [**v5.x**](/en/5x/api) | 18 | September 2024 | **ongoing** | +| [**v4.x**](/en/4x/api) | 0.10.0 | April 2014 | **ongoing** | +| [**v3.x**](/en/3x/api) | 0.8.0 | October 2012 | July 2015 | +| [**v2.x**](/2x/) | 0.4.1 | March 2011 | July 2012 | +| **v1.x** | 0.2.0 | December 2010 | March 2011 | +| **v0.14.x** | 0.1.98 | December 2010 | December 2010 | ## Commercial Support Options From 4cbf9b6afc5dabe148ba380f5aa346fb2e454867 Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Sat, 25 Apr 2026 17:02:53 +0000 Subject: [PATCH 4/5] fixup! --- .github/workflows/update-external-docs.yml | 29 ++++++++++++++++++---- netlify.toml | 3 +++ 2 files changed, 27 insertions(+), 5 deletions(-) diff --git a/.github/workflows/update-external-docs.yml b/.github/workflows/update-external-docs.yml index 04b77296f9..504e8e8cff 100644 --- a/.github/workflows/update-external-docs.yml +++ b/.github/workflows/update-external-docs.yml @@ -104,6 +104,14 @@ jobs: with: persist-credentials: false + - name: Set up Node.js + uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6 + with: + node-version: '24.13' + + - name: Install dependencies + run: npm ci + # see all the options at https://github.com/crowdin/github-action - name: Crowdin PR uses: crowdin/github-action@60debf382ee245b21794321190ad0501db89d8c1 # https://github.com/crowdin/github-action/releases/tag/v2.13.0 @@ -112,12 +120,23 @@ jobs: upload_translations: false download_translations: true localization_branch_name: crowdin/translations - create_pull_request: true - pull_request_title: 'i18n: new crowdin translations' - pull_request_body: > - New Crowdin translations from the [express.js crowdin project](https://express.crowdin.com/u/projects/1). cc: @expressjs/docs-wg - pull_request_base_branch_name: 'redesign' # TODO: update to "main" when we merge redesign into main + create_pull_request: false env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} CROWDIN_PROJECT_ID: ${{ secrets.CROWDIN_PROJECT_ID }} CROWDIN_PERSONAL_TOKEN: ${{ secrets.CROWDIN_PERSONAL_TOKEN }} + + - name: Format files + run: npm run format + + - name: Create Pull Request + uses: gr2m/create-or-update-pull-request-action@b65137ca591da0b9f43bad7b24df13050ea45d1b # v1.10.1 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + commit-message: 'i18n: new crowdin translations' + title: 'i18n: new crowdin translations' + body: > + New Crowdin translations from the [express.js crowdin project](https://express.crowdin.com/u/projects/1). cc: @expressjs/docs-wg + labels: docs + branch: crowdin/translations diff --git a/netlify.toml b/netlify.toml index a1680b2fff..72ac9b9d5f 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1,3 +1,6 @@ [build] command = "npm run build" publish = "dist" + +[build.environment] + NODE_OPTIONS = "--max-old-space-size=4096" From 0b7acfe6f3e8fdcf6a6976efd909df8107365908 Mon Sep 17 00:00:00 2001 From: Sebastian Beltran Date: Sat, 25 Apr 2026 17:03:10 +0000 Subject: [PATCH 5/5] Revert "remove fallbacks" This reverts commit a1b6e58a53e57c2d4af421fbd1c923bb0b5f850f. --- src/pages/[lang]/[...slug].astro | 121 +++++++++++++++++++++++++++++++ 1 file changed, 121 insertions(+) diff --git a/src/pages/[lang]/[...slug].astro b/src/pages/[lang]/[...slug].astro index a1596e7731..eda57c401b 100644 --- a/src/pages/[lang]/[...slug].astro +++ b/src/pages/[lang]/[...slug].astro @@ -12,6 +12,7 @@ import type { LanguageCode } from '@i18n/locales'; export async function getStaticPaths() { const DEFAULT_VERSION = '5x'; const VERSION_PREFIXES = ['5x', '4x', '3x']; + const DEFAULT_LANG = 'en'; const pages = await getCollection('docs'); const api = await getCollection('api'); @@ -24,6 +25,18 @@ export async function getStaticPaths() { props: { page: AnyPage; version?: string }; }> = []; + // Helper to create a map of existing content for fallback logic + const existingContent = new Map(); + pages.forEach((page) => { + const [lang, ...slugParts] = page.id.split('/'); + const fullSlug = slugParts.join('/'); + existingContent.set(`${lang}/${fullSlug}`, page); + }); + + api.forEach((page) => { + existingContent.set(`en/${page.id}`, page); + }); + pages.forEach((page) => { const [lang, ...slugParts] = page.id.split('/'); const fullSlug = slugParts.join('/'); @@ -46,6 +59,39 @@ export async function getStaticPaths() { }); }); + for (const lang of Object.keys(languages)) { + api.forEach((page) => { + const slugParts = page.id.split('/'); + const version = slugParts[0]; + const slug = page.id; + + paths.push({ + params: { lang, slug }, + props: { page, version }, + }); + }); + } + + const defaultVersionApiPages = api.filter((page) => page.id.startsWith(`${DEFAULT_VERSION}/`)); + + for (const lang of Object.keys(languages)) { + defaultVersionApiPages.forEach((page) => { + const [, ...restSlugParts] = page.id.split('/'); + const nonVersionedSlug = restSlugParts.join('/'); + + const exists = paths.some( + (p) => p.params.lang === lang && p.params.slug === nonVersionedSlug + ); + + if (!exists && nonVersionedSlug) { + paths.push({ + params: { lang, slug: nonVersionedSlug }, + props: { page, version: DEFAULT_VERSION }, + }); + } + }); + } + const defaultVersionPages = pages.filter((page) => { const [, ...slugParts] = page.id.split('/'); return slugParts[0] === DEFAULT_VERSION; @@ -65,6 +111,81 @@ export async function getStaticPaths() { } }); + // Fallback for non-versioned default-version slugs: use English content for missing languages + const englishDefaultVersionPages = defaultVersionPages.filter((p) => + p.id.startsWith(`${DEFAULT_LANG}/`) + ); + + for (const lang of Object.keys(languages)) { + if (lang === DEFAULT_LANG) continue; + + englishDefaultVersionPages.forEach((page) => { + const [, , ...restSlugParts] = page.id.split('/'); + const nonVersionedSlug = restSlugParts.join('/'); + + const exists = paths.some( + (p) => p.params.lang === lang && p.params.slug === nonVersionedSlug + ); + + if (!exists && nonVersionedSlug) { + paths.push({ + params: { lang, slug: nonVersionedSlug }, + props: { page, version: DEFAULT_VERSION }, + }); + } + }); + } + + // Fallback: Create paths for non-English languages using English pages content + for (const lang of Object.keys(languages)) { + if (lang === DEFAULT_LANG) continue; + + const englishContentPages = contentPages.filter((p) => p.id.startsWith(`${DEFAULT_LANG}/`)); + + englishContentPages.forEach((page) => { + const [, ...slugParts] = page.id.split('/'); + const fullSlug = slugParts.join('/'); + + const langSpecificExists = paths.some( + (p) => p.params.lang === lang && p.params.slug === fullSlug + ); + + if (!langSpecificExists) { + paths.push({ + params: { lang, slug: fullSlug }, + props: { page }, + }); + } + }); + } + + // Fallback: Create paths for non-English languages using English docs content + for (const lang of Object.keys(languages)) { + if (lang === DEFAULT_LANG) continue; // Skip English, already added + + const englishPages = pages.filter((p) => p.id.startsWith(`${DEFAULT_LANG}/`)); + + englishPages.forEach((page) => { + const [, ...slugParts] = page.id.split('/'); + const fullSlug = slugParts.join('/'); + + const langSpecificExists = paths.some( + (p) => p.params.lang === lang && p.params.slug === fullSlug + ); + + // If no language-specific version exists, add fallback to English + if (!langSpecificExists) { + paths.push({ + params: { lang, slug: fullSlug }, + props: { + page, + version: slugParts[0] === DEFAULT_VERSION ? DEFAULT_VERSION : slugParts[0], + }, + }); + } + }); + } + return paths; }