From 5ae88ade4aac6af121e17d1240d31a769461691c Mon Sep 17 00:00:00 2001 From: Duan Wei <75626015+Mkabaka@users.noreply.github.com> Date: Thu, 17 Jun 2021 09:57:18 +0800 Subject: [PATCH] Add v0.1.1 docs (#71) --- .../README.md | 0 docs/Reference_Doc/v0.1.0/README.md | 6 + .../v0.1.0/actuator_support/README.md | 0 .../custom_actuator_endpoint.md | 0 .../individed_actuator_port.md | 0 .../v0.1.0/actuator_support/quick_start.md | 0 .../actuator_support/restlight_endpoints.md | 0 .../v0.1.0/architecture/README.md | 0 .../v0.1.0/async_support/README.md | 0 .../v0.1.0/async_support/async_rules.md | 0 .../tips_of_completableFuture.md | 0 .../v0.1.0/jaxrs_support/README.md | 0 .../jaxrs_support/annotations_support.md | 0 .../v0.1.0/quick_start.md | 0 .../v0.1.0/restlight_core/README.md | 0 .../v0.1.0/restlight_core/use_jaxrs.md | 0 .../v0.1.0/restlight_core/use_springmvc.md | 0 .../v0.1.0/restlight_ext/README.md | 0 .../v0.1.0/restlight_ext/accesslog.md | 0 .../connection_creation_limit.md | 0 .../v0.1.0/restlight_ext/cors_origin.md | 0 .../restlight_ext/cpu_load_pretection.md | 0 .../v0.1.0/restlight_ext/ip_white_list.md | 0 .../v0.1.0/restlight_ext/multipart_support.md | 0 .../restlight_ext/signature_validation.md | 0 .../v0.1.0/restlight_ext/xss_support.md | 0 .../v0.1.0/restlight_for_spring/README.md | 0 .../restlight_for_spring/quick_start.md | 0 .../v0.1.0/restlight_server/README.md | 0 .../v0.1.0/restlight_server/handle_request.md | 0 .../v0.1.0/restlight_server/quick_start.md | 0 .../v0.1.0/restlight_server/terminology.md | 0 .../v0.1.0/restlight_starter/README.md | 0 .../ReturnValue Resolver Advice.md | 0 .../restlight_starter/argument_resolver.md | 0 .../argument_resolver_advice.md | 0 .../v0.1.0/restlight_starter/aware_ext.md | 0 .../restlight_starter/bean_validation.md | 0 .../restlight_starter/config_overview.md | 0 .../restlight_starter/config_support.md | 0 .../v0.1.0/restlight_starter/context_path.md | 0 .../restlight_starter/exception_resolver.md | 0 .../v0.1.0/restlight_starter/filter.md | 0 .../v0.1.0/restlight_starter/interceptor.md | 0 .../v0.1.0/restlight_starter/mock_mvc.md | 0 .../v0.1.0/restlight_starter/query_bean.md | 0 .../v0.1.0/restlight_starter/request_bean.md | 0 .../restlight_starter/returnValue_resolver.md | 0 .../v0.1.0/restlight_starter/routing_cache.md | 0 .../v0.1.0/restlight_starter/serialization.md | 0 .../restlight_starter/thread_scheduling.md | 0 .../v0.1.0/springmvc_support/README.md | 0 .../springmvc_support/annotations_support.md | 0 .../springmvc_support/exception_handler.md | 0 .../v0.1.0/threading_model/README.md | 0 .../v0.1.0/tips/README.md | 0 .../v0.1.0/tips/big_file_upload.md | 0 .../v0.1.0/tips/controller_semantics.md | 0 docs/Reference_Doc/v0.1.1/README.md | 6 + .../v0.1.1/actuator_support/README.md | 15 + .../custom_actuator_endpoint.md | 80 ++++ .../individed_actuator_port.md | 54 +++ .../v0.1.1/actuator_support/quick_start.md | 30 ++ .../actuator_support/restlight_endpoints.md | 316 ++++++++++++++++ .../v0.1.1/architecture/README.md | 91 +++++ .../v0.1.1/async_support/README.md | 15 + .../v0.1.1/async_support/async_rules.md | 61 ++++ .../tips_of_completableFuture.md | 9 + .../v0.1.1/jaxrs_support/README.md | 20 + .../jaxrs_support/annotations_support.md | 97 +++++ docs/Reference_Doc/v0.1.1/quick_start.md | 42 +++ .../v0.1.1/restlight_core/README.md | 33 ++ .../v0.1.1/restlight_core/use_jaxrs.md | 56 +++ .../v0.1.1/restlight_core/use_springmvc.md | 48 +++ .../v0.1.1/restlight_ext/README.md | 22 ++ .../v0.1.1/restlight_ext/accesslog.md | 45 +++ .../connection_creation_limit.md | 26 ++ .../v0.1.1/restlight_ext/cors_origin.md | 37 ++ .../restlight_ext/cpu_load_pretection.md | 38 ++ .../v0.1.1/restlight_ext/data_validate.md | 220 +++++++++++ .../v0.1.1/restlight_ext/ip_white_list.md | 31 ++ .../v0.1.1/restlight_ext/multipart_support.md | 79 ++++ .../restlight_ext/signature_validation.md | 114 ++++++ .../v0.1.1/restlight_ext/xss_support.md | 63 ++++ .../v0.1.1/restlight_for_spring/README.md | 28 ++ .../restlight_for_spring/quick_start.md | 56 +++ .../v0.1.1/restlight_server/README.md | 16 + .../v0.1.1/restlight_server/handle_request.md | 63 ++++ .../v0.1.1/restlight_server/quick_start.md | 34 ++ .../v0.1.1/restlight_server/terminology.md | 56 +++ .../v0.1.1/restlight_starter/README.md | 11 + .../ReturnValue Resolver Advice.md | 62 ++++ .../restlight_starter/argument_resolver.md | 232 ++++++++++++ .../argument_resolver_advice.md | 72 ++++ .../v0.1.1/restlight_starter/aware_ext.md | 39 ++ .../restlight_starter/config_overview.md | 75 ++++ .../restlight_starter/config_support.md | 47 +++ .../v0.1.1/restlight_starter/context_path.md | 34 ++ .../restlight_starter/exception_resolver.md | 38 ++ .../v0.1.1/restlight_starter/fail_fast.md | 20 + .../v0.1.1/restlight_starter/filter.md | 62 ++++ .../v0.1.1/restlight_starter/interceptor.md | 341 ++++++++++++++++++ .../v0.1.1/restlight_starter/mock_mvc.md | 149 ++++++++ .../v0.1.1/restlight_starter/query_bean.md | 36 ++ .../v0.1.1/restlight_starter/request_bean.md | 39 ++ .../restlight_starter/returnValue_resolver.md | 238 ++++++++++++ .../v0.1.1/restlight_starter/routing_cache.md | 36 ++ .../v0.1.1/restlight_starter/serialization.md | 313 ++++++++++++++++ .../restlight_starter/thread_scheduling.md | 86 +++++ .../v0.1.1/springmvc_support/README.md | 20 + .../springmvc_support/annotations_support.md | 134 +++++++ .../springmvc_support/exception_handler.md | 113 ++++++ .../v0.1.1/threading_model/README.md | 18 + .../v0.1.1/tips}/README.md | 4 +- .../v0.1.1/tips/big_file_upload.md | 7 + .../v0.1.1/tips/controller_semantics.md | 53 +++ 116 files changed, 4184 insertions(+), 2 deletions(-) rename docs/{Reference Doc => Reference_Doc}/README.md (100%) create mode 100644 docs/Reference_Doc/v0.1.0/README.md rename docs/{Reference Doc => Reference_Doc}/v0.1.0/actuator_support/README.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/actuator_support/custom_actuator_endpoint.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/actuator_support/individed_actuator_port.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/actuator_support/quick_start.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/actuator_support/restlight_endpoints.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/architecture/README.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/async_support/README.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/async_support/async_rules.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/async_support/tips_of_completableFuture.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/jaxrs_support/README.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/jaxrs_support/annotations_support.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/quick_start.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_core/README.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_core/use_jaxrs.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_core/use_springmvc.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_ext/README.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_ext/accesslog.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_ext/connection_creation_limit.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_ext/cors_origin.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_ext/cpu_load_pretection.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_ext/ip_white_list.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_ext/multipart_support.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_ext/signature_validation.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_ext/xss_support.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_for_spring/README.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_for_spring/quick_start.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_server/README.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_server/handle_request.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_server/quick_start.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_server/terminology.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/README.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/ReturnValue Resolver Advice.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/argument_resolver.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/argument_resolver_advice.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/aware_ext.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/bean_validation.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/config_overview.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/config_support.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/context_path.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/exception_resolver.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/filter.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/interceptor.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/mock_mvc.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/query_bean.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/request_bean.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/returnValue_resolver.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/routing_cache.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/serialization.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/restlight_starter/thread_scheduling.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/springmvc_support/README.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/springmvc_support/annotations_support.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/springmvc_support/exception_handler.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/threading_model/README.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/tips/README.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/tips/big_file_upload.md (100%) rename docs/{Reference Doc => Reference_Doc}/v0.1.0/tips/controller_semantics.md (100%) create mode 100644 docs/Reference_Doc/v0.1.1/README.md create mode 100644 docs/Reference_Doc/v0.1.1/actuator_support/README.md create mode 100644 docs/Reference_Doc/v0.1.1/actuator_support/custom_actuator_endpoint.md create mode 100644 docs/Reference_Doc/v0.1.1/actuator_support/individed_actuator_port.md create mode 100644 docs/Reference_Doc/v0.1.1/actuator_support/quick_start.md create mode 100644 docs/Reference_Doc/v0.1.1/actuator_support/restlight_endpoints.md create mode 100644 docs/Reference_Doc/v0.1.1/architecture/README.md create mode 100644 docs/Reference_Doc/v0.1.1/async_support/README.md create mode 100644 docs/Reference_Doc/v0.1.1/async_support/async_rules.md create mode 100644 docs/Reference_Doc/v0.1.1/async_support/tips_of_completableFuture.md create mode 100644 docs/Reference_Doc/v0.1.1/jaxrs_support/README.md create mode 100644 docs/Reference_Doc/v0.1.1/jaxrs_support/annotations_support.md create mode 100644 docs/Reference_Doc/v0.1.1/quick_start.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_core/README.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_core/use_jaxrs.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_core/use_springmvc.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_ext/README.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_ext/accesslog.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_ext/connection_creation_limit.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_ext/cors_origin.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_ext/cpu_load_pretection.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_ext/data_validate.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_ext/ip_white_list.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_ext/multipart_support.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_ext/signature_validation.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_ext/xss_support.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_for_spring/README.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_for_spring/quick_start.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_server/README.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_server/handle_request.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_server/quick_start.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_server/terminology.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/README.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/ReturnValue Resolver Advice.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/argument_resolver.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/argument_resolver_advice.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/aware_ext.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/config_overview.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/config_support.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/context_path.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/exception_resolver.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/fail_fast.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/filter.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/interceptor.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/mock_mvc.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/query_bean.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/request_bean.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/returnValue_resolver.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/routing_cache.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/serialization.md create mode 100644 docs/Reference_Doc/v0.1.1/restlight_starter/thread_scheduling.md create mode 100644 docs/Reference_Doc/v0.1.1/springmvc_support/README.md create mode 100644 docs/Reference_Doc/v0.1.1/springmvc_support/annotations_support.md create mode 100644 docs/Reference_Doc/v0.1.1/springmvc_support/exception_handler.md create mode 100644 docs/Reference_Doc/v0.1.1/threading_model/README.md rename docs/{Reference Doc/v0.1.0 => Reference_Doc/v0.1.1/tips}/README.md (64%) create mode 100644 docs/Reference_Doc/v0.1.1/tips/big_file_upload.md create mode 100644 docs/Reference_Doc/v0.1.1/tips/controller_semantics.md diff --git a/docs/Reference Doc/README.md b/docs/Reference_Doc/README.md similarity index 100% rename from docs/Reference Doc/README.md rename to docs/Reference_Doc/README.md diff --git a/docs/Reference_Doc/v0.1.0/README.md b/docs/Reference_Doc/v0.1.0/README.md new file mode 100644 index 00000000..9e3801fc --- /dev/null +++ b/docs/Reference_Doc/v0.1.0/README.md @@ -0,0 +1,6 @@ +--- +sort: 2 +--- + +# V0.1.0 +{% include list.liquid all=true %} diff --git a/docs/Reference Doc/v0.1.0/actuator_support/README.md b/docs/Reference_Doc/v0.1.0/actuator_support/README.md similarity index 100% rename from docs/Reference Doc/v0.1.0/actuator_support/README.md rename to docs/Reference_Doc/v0.1.0/actuator_support/README.md diff --git a/docs/Reference Doc/v0.1.0/actuator_support/custom_actuator_endpoint.md b/docs/Reference_Doc/v0.1.0/actuator_support/custom_actuator_endpoint.md similarity index 100% rename from docs/Reference Doc/v0.1.0/actuator_support/custom_actuator_endpoint.md rename to docs/Reference_Doc/v0.1.0/actuator_support/custom_actuator_endpoint.md diff --git a/docs/Reference Doc/v0.1.0/actuator_support/individed_actuator_port.md b/docs/Reference_Doc/v0.1.0/actuator_support/individed_actuator_port.md similarity index 100% rename from docs/Reference Doc/v0.1.0/actuator_support/individed_actuator_port.md rename to docs/Reference_Doc/v0.1.0/actuator_support/individed_actuator_port.md diff --git a/docs/Reference Doc/v0.1.0/actuator_support/quick_start.md b/docs/Reference_Doc/v0.1.0/actuator_support/quick_start.md similarity index 100% rename from docs/Reference Doc/v0.1.0/actuator_support/quick_start.md rename to docs/Reference_Doc/v0.1.0/actuator_support/quick_start.md diff --git a/docs/Reference Doc/v0.1.0/actuator_support/restlight_endpoints.md b/docs/Reference_Doc/v0.1.0/actuator_support/restlight_endpoints.md similarity index 100% rename from docs/Reference Doc/v0.1.0/actuator_support/restlight_endpoints.md rename to docs/Reference_Doc/v0.1.0/actuator_support/restlight_endpoints.md diff --git a/docs/Reference Doc/v0.1.0/architecture/README.md b/docs/Reference_Doc/v0.1.0/architecture/README.md similarity index 100% rename from docs/Reference Doc/v0.1.0/architecture/README.md rename to docs/Reference_Doc/v0.1.0/architecture/README.md diff --git a/docs/Reference Doc/v0.1.0/async_support/README.md b/docs/Reference_Doc/v0.1.0/async_support/README.md similarity index 100% rename from docs/Reference Doc/v0.1.0/async_support/README.md rename to docs/Reference_Doc/v0.1.0/async_support/README.md diff --git a/docs/Reference Doc/v0.1.0/async_support/async_rules.md b/docs/Reference_Doc/v0.1.0/async_support/async_rules.md similarity index 100% rename from docs/Reference Doc/v0.1.0/async_support/async_rules.md rename to docs/Reference_Doc/v0.1.0/async_support/async_rules.md diff --git a/docs/Reference Doc/v0.1.0/async_support/tips_of_completableFuture.md b/docs/Reference_Doc/v0.1.0/async_support/tips_of_completableFuture.md similarity index 100% rename from docs/Reference Doc/v0.1.0/async_support/tips_of_completableFuture.md rename to docs/Reference_Doc/v0.1.0/async_support/tips_of_completableFuture.md diff --git a/docs/Reference Doc/v0.1.0/jaxrs_support/README.md b/docs/Reference_Doc/v0.1.0/jaxrs_support/README.md similarity index 100% rename from docs/Reference Doc/v0.1.0/jaxrs_support/README.md rename to docs/Reference_Doc/v0.1.0/jaxrs_support/README.md diff --git a/docs/Reference Doc/v0.1.0/jaxrs_support/annotations_support.md b/docs/Reference_Doc/v0.1.0/jaxrs_support/annotations_support.md similarity index 100% rename from docs/Reference Doc/v0.1.0/jaxrs_support/annotations_support.md rename to docs/Reference_Doc/v0.1.0/jaxrs_support/annotations_support.md diff --git a/docs/Reference Doc/v0.1.0/quick_start.md b/docs/Reference_Doc/v0.1.0/quick_start.md similarity index 100% rename from docs/Reference Doc/v0.1.0/quick_start.md rename to docs/Reference_Doc/v0.1.0/quick_start.md diff --git a/docs/Reference Doc/v0.1.0/restlight_core/README.md b/docs/Reference_Doc/v0.1.0/restlight_core/README.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_core/README.md rename to docs/Reference_Doc/v0.1.0/restlight_core/README.md diff --git a/docs/Reference Doc/v0.1.0/restlight_core/use_jaxrs.md b/docs/Reference_Doc/v0.1.0/restlight_core/use_jaxrs.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_core/use_jaxrs.md rename to docs/Reference_Doc/v0.1.0/restlight_core/use_jaxrs.md diff --git a/docs/Reference Doc/v0.1.0/restlight_core/use_springmvc.md b/docs/Reference_Doc/v0.1.0/restlight_core/use_springmvc.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_core/use_springmvc.md rename to docs/Reference_Doc/v0.1.0/restlight_core/use_springmvc.md diff --git a/docs/Reference Doc/v0.1.0/restlight_ext/README.md b/docs/Reference_Doc/v0.1.0/restlight_ext/README.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_ext/README.md rename to docs/Reference_Doc/v0.1.0/restlight_ext/README.md diff --git a/docs/Reference Doc/v0.1.0/restlight_ext/accesslog.md b/docs/Reference_Doc/v0.1.0/restlight_ext/accesslog.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_ext/accesslog.md rename to docs/Reference_Doc/v0.1.0/restlight_ext/accesslog.md diff --git a/docs/Reference Doc/v0.1.0/restlight_ext/connection_creation_limit.md b/docs/Reference_Doc/v0.1.0/restlight_ext/connection_creation_limit.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_ext/connection_creation_limit.md rename to docs/Reference_Doc/v0.1.0/restlight_ext/connection_creation_limit.md diff --git a/docs/Reference Doc/v0.1.0/restlight_ext/cors_origin.md b/docs/Reference_Doc/v0.1.0/restlight_ext/cors_origin.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_ext/cors_origin.md rename to docs/Reference_Doc/v0.1.0/restlight_ext/cors_origin.md diff --git a/docs/Reference Doc/v0.1.0/restlight_ext/cpu_load_pretection.md b/docs/Reference_Doc/v0.1.0/restlight_ext/cpu_load_pretection.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_ext/cpu_load_pretection.md rename to docs/Reference_Doc/v0.1.0/restlight_ext/cpu_load_pretection.md diff --git a/docs/Reference Doc/v0.1.0/restlight_ext/ip_white_list.md b/docs/Reference_Doc/v0.1.0/restlight_ext/ip_white_list.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_ext/ip_white_list.md rename to docs/Reference_Doc/v0.1.0/restlight_ext/ip_white_list.md diff --git a/docs/Reference Doc/v0.1.0/restlight_ext/multipart_support.md b/docs/Reference_Doc/v0.1.0/restlight_ext/multipart_support.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_ext/multipart_support.md rename to docs/Reference_Doc/v0.1.0/restlight_ext/multipart_support.md diff --git a/docs/Reference Doc/v0.1.0/restlight_ext/signature_validation.md b/docs/Reference_Doc/v0.1.0/restlight_ext/signature_validation.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_ext/signature_validation.md rename to docs/Reference_Doc/v0.1.0/restlight_ext/signature_validation.md diff --git a/docs/Reference Doc/v0.1.0/restlight_ext/xss_support.md b/docs/Reference_Doc/v0.1.0/restlight_ext/xss_support.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_ext/xss_support.md rename to docs/Reference_Doc/v0.1.0/restlight_ext/xss_support.md diff --git a/docs/Reference Doc/v0.1.0/restlight_for_spring/README.md b/docs/Reference_Doc/v0.1.0/restlight_for_spring/README.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_for_spring/README.md rename to docs/Reference_Doc/v0.1.0/restlight_for_spring/README.md diff --git a/docs/Reference Doc/v0.1.0/restlight_for_spring/quick_start.md b/docs/Reference_Doc/v0.1.0/restlight_for_spring/quick_start.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_for_spring/quick_start.md rename to docs/Reference_Doc/v0.1.0/restlight_for_spring/quick_start.md diff --git a/docs/Reference Doc/v0.1.0/restlight_server/README.md b/docs/Reference_Doc/v0.1.0/restlight_server/README.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_server/README.md rename to docs/Reference_Doc/v0.1.0/restlight_server/README.md diff --git a/docs/Reference Doc/v0.1.0/restlight_server/handle_request.md b/docs/Reference_Doc/v0.1.0/restlight_server/handle_request.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_server/handle_request.md rename to docs/Reference_Doc/v0.1.0/restlight_server/handle_request.md diff --git a/docs/Reference Doc/v0.1.0/restlight_server/quick_start.md b/docs/Reference_Doc/v0.1.0/restlight_server/quick_start.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_server/quick_start.md rename to docs/Reference_Doc/v0.1.0/restlight_server/quick_start.md diff --git a/docs/Reference Doc/v0.1.0/restlight_server/terminology.md b/docs/Reference_Doc/v0.1.0/restlight_server/terminology.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_server/terminology.md rename to docs/Reference_Doc/v0.1.0/restlight_server/terminology.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/README.md b/docs/Reference_Doc/v0.1.0/restlight_starter/README.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/README.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/README.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/ReturnValue Resolver Advice.md b/docs/Reference_Doc/v0.1.0/restlight_starter/ReturnValue Resolver Advice.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/ReturnValue Resolver Advice.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/ReturnValue Resolver Advice.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/argument_resolver.md b/docs/Reference_Doc/v0.1.0/restlight_starter/argument_resolver.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/argument_resolver.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/argument_resolver.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/argument_resolver_advice.md b/docs/Reference_Doc/v0.1.0/restlight_starter/argument_resolver_advice.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/argument_resolver_advice.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/argument_resolver_advice.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/aware_ext.md b/docs/Reference_Doc/v0.1.0/restlight_starter/aware_ext.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/aware_ext.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/aware_ext.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/bean_validation.md b/docs/Reference_Doc/v0.1.0/restlight_starter/bean_validation.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/bean_validation.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/bean_validation.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/config_overview.md b/docs/Reference_Doc/v0.1.0/restlight_starter/config_overview.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/config_overview.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/config_overview.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/config_support.md b/docs/Reference_Doc/v0.1.0/restlight_starter/config_support.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/config_support.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/config_support.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/context_path.md b/docs/Reference_Doc/v0.1.0/restlight_starter/context_path.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/context_path.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/context_path.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/exception_resolver.md b/docs/Reference_Doc/v0.1.0/restlight_starter/exception_resolver.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/exception_resolver.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/exception_resolver.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/filter.md b/docs/Reference_Doc/v0.1.0/restlight_starter/filter.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/filter.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/filter.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/interceptor.md b/docs/Reference_Doc/v0.1.0/restlight_starter/interceptor.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/interceptor.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/interceptor.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/mock_mvc.md b/docs/Reference_Doc/v0.1.0/restlight_starter/mock_mvc.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/mock_mvc.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/mock_mvc.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/query_bean.md b/docs/Reference_Doc/v0.1.0/restlight_starter/query_bean.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/query_bean.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/query_bean.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/request_bean.md b/docs/Reference_Doc/v0.1.0/restlight_starter/request_bean.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/request_bean.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/request_bean.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/returnValue_resolver.md b/docs/Reference_Doc/v0.1.0/restlight_starter/returnValue_resolver.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/returnValue_resolver.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/returnValue_resolver.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/routing_cache.md b/docs/Reference_Doc/v0.1.0/restlight_starter/routing_cache.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/routing_cache.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/routing_cache.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/serialization.md b/docs/Reference_Doc/v0.1.0/restlight_starter/serialization.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/serialization.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/serialization.md diff --git a/docs/Reference Doc/v0.1.0/restlight_starter/thread_scheduling.md b/docs/Reference_Doc/v0.1.0/restlight_starter/thread_scheduling.md similarity index 100% rename from docs/Reference Doc/v0.1.0/restlight_starter/thread_scheduling.md rename to docs/Reference_Doc/v0.1.0/restlight_starter/thread_scheduling.md diff --git a/docs/Reference Doc/v0.1.0/springmvc_support/README.md b/docs/Reference_Doc/v0.1.0/springmvc_support/README.md similarity index 100% rename from docs/Reference Doc/v0.1.0/springmvc_support/README.md rename to docs/Reference_Doc/v0.1.0/springmvc_support/README.md diff --git a/docs/Reference Doc/v0.1.0/springmvc_support/annotations_support.md b/docs/Reference_Doc/v0.1.0/springmvc_support/annotations_support.md similarity index 100% rename from docs/Reference Doc/v0.1.0/springmvc_support/annotations_support.md rename to docs/Reference_Doc/v0.1.0/springmvc_support/annotations_support.md diff --git a/docs/Reference Doc/v0.1.0/springmvc_support/exception_handler.md b/docs/Reference_Doc/v0.1.0/springmvc_support/exception_handler.md similarity index 100% rename from docs/Reference Doc/v0.1.0/springmvc_support/exception_handler.md rename to docs/Reference_Doc/v0.1.0/springmvc_support/exception_handler.md diff --git a/docs/Reference Doc/v0.1.0/threading_model/README.md b/docs/Reference_Doc/v0.1.0/threading_model/README.md similarity index 100% rename from docs/Reference Doc/v0.1.0/threading_model/README.md rename to docs/Reference_Doc/v0.1.0/threading_model/README.md diff --git a/docs/Reference Doc/v0.1.0/tips/README.md b/docs/Reference_Doc/v0.1.0/tips/README.md similarity index 100% rename from docs/Reference Doc/v0.1.0/tips/README.md rename to docs/Reference_Doc/v0.1.0/tips/README.md diff --git a/docs/Reference Doc/v0.1.0/tips/big_file_upload.md b/docs/Reference_Doc/v0.1.0/tips/big_file_upload.md similarity index 100% rename from docs/Reference Doc/v0.1.0/tips/big_file_upload.md rename to docs/Reference_Doc/v0.1.0/tips/big_file_upload.md diff --git a/docs/Reference Doc/v0.1.0/tips/controller_semantics.md b/docs/Reference_Doc/v0.1.0/tips/controller_semantics.md similarity index 100% rename from docs/Reference Doc/v0.1.0/tips/controller_semantics.md rename to docs/Reference_Doc/v0.1.0/tips/controller_semantics.md diff --git a/docs/Reference_Doc/v0.1.1/README.md b/docs/Reference_Doc/v0.1.1/README.md new file mode 100644 index 00000000..a73dc01e --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/README.md @@ -0,0 +1,6 @@ +--- +sort: 1 +--- + +# V0.1.1 +{% include list.liquid all=true %} diff --git a/docs/Reference_Doc/v0.1.1/actuator_support/README.md b/docs/Reference_Doc/v0.1.1/actuator_support/README.md new file mode 100644 index 00000000..d10ea14f --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/actuator_support/README.md @@ -0,0 +1,15 @@ +--- +sort: 5 +--- + +# Spring Boot Actuator支持 + +Restlight适配了[Spring Boot Actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-project/spring-boot-actuator)， 提供详细的健康检查以及监控等接口 + +```note +仅支持`Spring Boot2X`版本 +``` + +{% include list.liquid all=true %} + + diff --git a/docs/Reference_Doc/v0.1.1/actuator_support/custom_actuator_endpoint.md b/docs/Reference_Doc/v0.1.1/actuator_support/custom_actuator_endpoint.md new file mode 100644 index 00000000..a93c3246 --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/actuator_support/custom_actuator_endpoint.md @@ -0,0 +1,80 @@ +--- +sort: 3 +--- + +# 自定义`Endpoint` + +用户可以自己定义`Endpoint`实现定制化的健康检查接口 + +eg + +```java +@Endpoint(id = "appId") +public class AppIdEndpoint { + + @ReadOperation + public String appId() { + return "esa-restlight"; + } +} +``` + +上面的代码自定义了一个`Endpoint`接口并返回appid + +将上面接口注入Spring容器 + +```java +@Bean +public AppIdEndpoint endpoint() { + return new AppIdEndpoint(); +} +``` + +启动之后访问`curl -X GET localhost:8080/actuator/appId` + +返回 + +```properties +esa-restlight +``` + +## 自定义异步`EndPoint` + +用户可以自己定义基于`Completablefture`的`Endpoint`实现定制化的健康检查接口 + +eg + +```java +@Endpoint(id = "appId") +public class AppIdEndpoint { + + @ReadOperation + public CompletableFuture appId() { + return CompletableFuture.supplyAsync(() -> { + + // do something... + + return "esa-restlight"; + }); + } +} +``` + +上面的代码自定义了一个异步的`Endpoint`接口并返回appid + +将上面接口注入Spring容器 + +```java +@Bean +public AppIdEndpoint endpoint() { + return new AppIdEndpoint(); +} +``` + +启动之后访问`curl -X GET localhost:8080/actuator/appId` + +返回 + +```pro +esa-restlight +``` diff --git a/docs/Reference_Doc/v0.1.1/actuator_support/individed_actuator_port.md b/docs/Reference_Doc/v0.1.1/actuator_support/individed_actuator_port.md new file mode 100644 index 00000000..2cc5b390 --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/actuator_support/individed_actuator_port.md @@ -0,0 +1,54 @@ +--- +sort: 4 +--- + +# 使用独立的端口 + +默认情况下健康检查的接口都将与`Restight`使用同一个HttpServer服务， 如果需要将健康检查接口与业务接口分别使用不同的端口则可以添加一下配置 + +```properties +#配置健康检查暴露的端口 +management.server.port=8081 +``` + +启动后看到日志打印 + +```properties +Started Restlight(Actuator) server in 386 millis on port:8081 +``` + +```warning +独立端口启动后所有的`Filter`, 序列化， `ArgumentResolver`等扩展将与`Restlight`隔离 +``` + +## 辅助配置 + +`SpringBoot`场景下大多数的配置可通过`application.properties`（或者yaml）配置文件即可完成配置，但是配置文件配置还是会有其缺陷 + +- 无法动态配置（这里的动态指的是通过代码计算等方式决定配置） +- 语法表达能力有限 +- 配置过多变得冗杂 + +等问题。 + +### `ManagementConfigure` + +用于支持`SpringBoot`场景显式配置 + +eg. + +```java +@Bean +public ManagementConfigure configure() { + return restlight -> { + restlight.address(8081) + .addFilter((request, response, chain) -> { + // biz logic + return chain.doFilter(request, response); + }); + restlight.options().setCoreBizThreads(16); + restlight.options().setMaxBizThreads(32); + // more... + }; +} +``` \ No newline at end of file diff --git a/docs/Reference_Doc/v0.1.1/actuator_support/quick_start.md b/docs/Reference_Doc/v0.1.1/actuator_support/quick_start.md new file mode 100644 index 00000000..f5da0361 --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/actuator_support/quick_start.md @@ -0,0 +1,30 @@ +--- +sort: 1 +--- + +# Quick Start + +引入Maven依赖： + +```xml + + org.springframework.boot + spring-boot-starter-actuator + 2.1.1.RELEASE + + + io.esastack + restlight-starter-actuator + ${restlight.version} + +``` + +```note +Actuator的版本请配合对应的Spring Boot版本引入 +``` + +访问 `Get` `localhost:8080/actuator/info`返回`{}` + +```tip +Spring Boot2.0之后的Atctuator默认只开启了`info`和`health`两个接口， 可以使用`management.endpoints.web.exposure.include=info,health,foo`开启。 +``` \ No newline at end of file diff --git a/docs/Reference_Doc/v0.1.1/actuator_support/restlight_endpoints.md b/docs/Reference_Doc/v0.1.1/actuator_support/restlight_endpoints.md new file mode 100644 index 00000000..d45dc757 --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/actuator_support/restlight_endpoints.md @@ -0,0 +1,316 @@ +--- +sort: 2 +--- + +# Restlight Endpoint扩展 + +在[Spring Boot Actuator](https://github.com/spring-projects/spring-boot/tree/master/spring-boot-project/spring-boot-actuator)基础之上`Restlight`提供额外的功能扩展 + +## 业务线程池Metrics + +```note +业务线程当前采用JUC的`ThreadPoolExecutor`实现，后续版本可能会换成自定义实现，因此Metrics内容可能发生变更 +``` + +### 1、Json 格式 + +**`Get` `actuator/bizthreadpool`** + +Example: + +```shell +curl -X GET localhost:8080/actuator/bizthreadpool +``` + +返回 + +```json +{ + "corePoolSize": 4, + "maxPoolSize": 4, + "queueLength": 1024, + "keepAliveTimeSeconds": 180, + "activeCount": 1, + "poolSize": 4, + "largestPoolSize": 4, + "taskCount": 6, + "queueCount": 0, + "completedTaskCount": 5 +} +``` +### 2、Prometheus 格式 + +**`Get` `actuator/bizthreadpool4prometheus`** + +Example: + +```shell +curl -X GET localhost:8080/actuator/bizthreadpool4prometheus +``` + +返回 + +``` +# HELP core_pool_size +# TYPE core_pool_size gauge +core_pool_size 1.0 +# HELP active_count +# TYPE active_count gauge +active_count 0.0 +# HELP queue_count +# TYPE queue_count gauge +queue_count 0.0 +# HELP largest_pool_size +# TYPE largest_pool_size gauge +largest_pool_size 0.0 +# HELP reject_task_count +# TYPE reject_task_count gauge +reject_task_count -1.0 +# HELP max_pool_size +# TYPE max_pool_size gauge +max_pool_size 2.0 +# HELP pool_size +# TYPE pool_size gauge +pool_size 0.0 +# HELP queue_length +# TYPE queue_length gauge +queue_length 1024.0 +# HELP keep_alive_time_seconds +# TYPE keep_alive_time_seconds gauge +keep_alive_time_seconds 60.0 +# HELP task_count +# TYPE task_count gauge +task_count 0.0 +# HELP completed_task_count +# TYPE completed_task_count gauge +completed_task_count 0.0 +``` +## 业务线程池扩缩容 + +**`Post` `actuator/bizthreadpool`** + +```shell +curl -X POST -H "Content-Type:application/json" -d "{\"corePoolSize\":\"1\",\"maxPoolSize\":\"2\"}" localhost:8080/actuator/bizthreadpool +``` + +## IO线程池Metrics +### 1、Json 格式 +**`Get` `actuator/ioexecutor`** + +Example: + +```shell +curl -X GET localhost:8080/actuator/ioexecutor +``` + +返回 + +```json +{ + "childExecutors": [ + { + "pendingTasks": 0, + "maxPendingTasks": 2147483647, + "ioRatio": 50, + "taskQueueSize": 0, + "tailTaskQueueSize": 0, + "threadName": "Netty-I/O-1#0", + "threadPriority": 5, + "threadState": "RUNNABLE" + }, + { + "pendingTasks": 0, + "maxPendingTasks": 2147483647, + "ioRatio": 50, + "taskQueueSize": 0, + "tailTaskQueueSize": 0, + "threadName": "Netty-I/O-1#1", + "threadPriority": 5, + "threadState": "RUNNABLE" + } + ], + "threadCount": 2, + "pendingTasks": 0, + "threadStates": { + "RUNNABLE": 2 + }, + "terminated": false, + "shutDown": false +} +``` +### 2、Prometheus 格式 + +**`Get` `actuator/ioexecutor4prometheus`** + +Example: + +```shell +curl -X GET localhost:8080/actuator/ioexecutor4prometheus +``` + +返回 + +``` +# HELP pending_tasks_netty_io_1_0 +# TYPE pending_tasks_netty_io_1_0 gauge +pending_tasks_netty_io_1_0 0.0 +# HELP thread_state_netty_io_1_1 +# TYPE thread_state_netty_io_1_1 gauge +thread_state_netty_io_1_1 1.0 +# HELP thread_states_runnable +# TYPE thread_states_runnable gauge +thread_states_runnable 2.0 +# HELP task_queue_size_netty_io_1_1 +# TYPE task_queue_size_netty_io_1_1 gauge +task_queue_size_netty_io_1_1 0.0 +# HELP thread_priority +# TYPE thread_priority gauge +thread_priority 5.0 +# HELP pending_tasks_netty_io_1_1 +# TYPE pending_tasks_netty_io_1_1 gauge +pending_tasks_netty_io_1_1 0.0 +# HELP pending_tasks +# TYPE pending_tasks gauge +pending_tasks 0.0 +# HELP terminated +# TYPE terminated gauge +terminated 0.0 +# HELP max_pending_tasks +# TYPE max_pending_tasks gauge +max_pending_tasks 2.147483647E9 +# HELP thread_state_netty_io_1_0 +# TYPE thread_state_netty_io_1_0 gauge +thread_state_netty_io_1_0 1.0 +# HELP io_ratio +# TYPE io_ratio gauge +io_ratio 50.0 +# HELP shutdown +# TYPE shutdown gauge +shutdown 0.0 +# HELP task_queue_size_netty_io_1_0 +# TYPE task_queue_size_netty_io_1_0 gauge +task_queue_size_netty_io_1_0 0.0 +# HELP thread_count +# TYPE thread_count gauge +thread_count 2.0 +``` + +```warning +比较昂贵的操作， 不建议频繁调用 +``` + +当使用的Springboot版本为2.3.X及以上时，需要在pom文件中引入micrometer-registry-prometheus 1.5.1及以上版本，此处以1.5.1版本为例，直接引入即可覆盖原有版本，具体操作如下： + +```xml + + io.micrometer + micrometer-registry-prometheus + 1.5.1 + +``` + +## 获取Restlight所有配置信息 + +**`Get` `actuator/restlightconfigs`** + +Example: + +```shell +curl -X GET localhost:8080/actuator/restlightconfigs +``` + +返回： + +```json +{ + "http2Enable": false, + "useNativeTransports": false, + "connectorThreads": 1, + "ioThreads": 2, + "coreBizThreads": 4, + "maxBizThreads": 4, + "blockingQueueLength": 1024, + "keepAliveTimeSeconds": 180, + "executorTerminationTimeoutSeconds": 60, + "compress": false, + "decompress": false, + "maxContentLength": 4194304, + "maxInitialLineLength": 4096, + "maxHeaderSize": 8192, + "soRcvbuf": 0, + "soSendbuf": 0, + "soBacklog": 128, + "writeBufferHighWaterMark": 65536, + "idleTimeSeconds": 60, + "keepAliveEnable": true, + "https": { + "enable": false, + "handshakeTimeoutMillis": 3000, + "certificatePath": null, + "privateKeyPath": null, + "sessionTicketKeyPath": null, + "sessionTimeoutSeconds": 0, + "sessionCacheEnable": false, + "sessionCacheSize": 0, + "enabledCipherSuites": [], + "enabledProtocols": [] + }, + "scheduling": { + "defaultStrategy": "BIZ", + "bufferSize": 4096, + "batchingSize": 50 + }, + "route": { + "useCachedRouting": true, + "cacheRatio": 10, + "computeRate": 1 + }, + "contextPath": null, + "validationMessageFile": null, + "serialize": { + "request": { + "negotiation": false, + "negotiationParam": "format" + }, + "response": { + "negotiation": false, + "negotiationParam": "format" + } + }, + "ext": {}, + "host": null, + "port": 8080, + "unixDomainSocketFile": null, + "printBanner": true, + "warmUp": { + "enable": false, + "delay": 0 + } +} +``` + +## 强制Full GC + +**`Post` `actuator/forcefgc`** + +Example: + +```shell +curl -X POST localhost:8080/actuator/forcefgc +``` + +## 修改优雅停机等待时间 + +**`Post` `actuator/terminationtimeout`**。 + +Example： + +```shell +curl -X POST -H "Content-Type:application/json" -d "{\"timeout\": 120}" localhost:8080/actuator/terminationtimeout +``` + +返回 + +``` +Success +``` \ No newline at end of file diff --git a/docs/Reference_Doc/v0.1.1/architecture/README.md b/docs/Reference_Doc/v0.1.1/architecture/README.md new file mode 100644 index 00000000..95fcb542 --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/architecture/README.md @@ -0,0 +1,91 @@ +--- +sort: 1 +--- +# 架构 + +## 设计原则 + +- 高兼容性 +- 极致性能 +- 全链路异步 +- 易用 +- 可扩展 + +## 功能架构 +**分层架构设计** + +![Architecture](../../../img/architecture.png) + +架构图中`ESA HttpServer`, `Restlight Server`, `Restlight Core`, `Restlight for Spring`, `Restlight Starter`几个模块均可作为一个独立的模块使用， 满足不同场景下的需求。 + +### ESA HttpServer + +基于`Netty` 实现的一个简易的[HttpServer](https://github.com/esastack/esa-httpserver)， 支持Http1.1/Http2以及Https等 + +### Restlight Server + +在`ESA HttpServer`基础之上封装了 + +- 引入业务线程池 +- `Filter` +- 请求路由（根据url, method, header等条件将请求路由到对应的Handler） +- 基于`CompletableFuture`的响应式编程支持 +- 线程调度 +- ... + +#### 对应启动入口类`esa.restlight.server.Restlite` + +```tip +适合各类框架，中间件等基础组建中启动或期望使用代码显示启动HttpServer的场景 +``` + +### Restlight Core + +在`Restlight Server`之上， 扩展支持了`Controller`方式（在`Controller`类中通过诸如`@RequestMappng`等注解的方式构造请求处理逻辑）完成业务逻辑以及诸多常用功能 + +- `HandlerInterceptor`: 拦截器 +- `ExceptionHandler`: 全局异常处理器 +- `BeanValidation`: 参数校验 +- `ArgumentResolver`: 参数解析扩展 +- `ReturnValueResolver`: 返回值解析扩展 +- `RequestSerializer`: 请求序列化器（通常负责反序列化Body内容） +- `ResposneSerializer`: 响应序列化器（通常负责序列化响应对象到Body） +- 内置`Jackson`, `Fastjson`, `Gson`, `ProtoBuf`序列化支持 +- ... + +#### 对应启动入口类`esa.restlight.core.Restlight` + +```tip +适合各类框架，中间件等基础组建中启动或期望使用代码显示启动HttpServer的场景 +``` + +### Restlight SpringMVC & Restlight JAX-RS + +- `Restlight SpringMVC`对`SpringMVC`中的注解使用习惯的`Restlight Core`的扩展实现（`@RequestMapping`, `@RequestParam`等）。 + +- `Restlight JAX-RS`对`JAX-RS`中的注解使用习惯的`Restlight Core`的扩展实现（`@Path`, `@GET`, `@QueryParam`等）。 + +### Restlight for Spring + +在`Restlight Core`基础上支持在`Spring`场景下通过`ApplicationContext`容器自动配置各种内容（`RestlightOptions`, 从容器中自动配置`Filter`, `Controller`, `ControllerAdvice`等） + +```tip +适合`Spring Boot`场景 +``` + +### Restlight Starter + +在`Restlight for Spring`基础上支持在`Spring Boot`场景的自动配置 + +```tip +适合`Spring Boot`场景 + ``` + +### Restlight Actuator + +在`Restlight Starter`基础上支持在`Spring Boot Actuator`原生各种`Endpoint`s支持以及`Restlight`独有的`Endpoint`s。 + +```tip +适合`Spring Boot Actuator`场景 +``` + diff --git a/docs/Reference_Doc/v0.1.1/async_support/README.md b/docs/Reference_Doc/v0.1.1/async_support/README.md new file mode 100644 index 00000000..d41de9bf --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/async_support/README.md @@ -0,0 +1,15 @@ +--- +sort: 11 +--- + +# 全链路异步 + +当前`Restlight`版本支持`Filter` ， `HandlerInterceptor`, `Controller`, `ExceptionHandler`异步。 + +对应处理链路 + +![restlightexecution.png](../../../img/execution.png) + +上述对应着一个请求的完成执行链路， 并且每个链路都支持异步。 + +{% include list.liquid all=true %} diff --git a/docs/Reference_Doc/v0.1.1/async_support/async_rules.md b/docs/Reference_Doc/v0.1.1/async_support/async_rules.md new file mode 100644 index 00000000..888c0cb6 --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/async_support/async_rules.md @@ -0,0 +1,61 @@ +--- +sort: 1 +--- + +# Restlight 异步保证 + +- **`Restlight`保证在框架层面对所有的`CompletableFuture`处理都不会主动的切换执行的线程**。 + + + +这个保证使得用户无需担心不知道自己的代码将会在什么线程上执行。 + +```tip +上面的保证意味着如果用字自己切换了执行的线程（通常异步可能都会做这个动作）， 那么这个节点以后的所有代码都将在切换后的线程上执行， 而不是在`Restlight`的业务线程池。 +``` + +**例** + +用户在`HandlerInterceptor`中写下了如下代码 + +```java +private final Executor customExecutor = ...; + +@Override +public CompletableFuture preHandle0(AsyncRequest request, + AsyncResponse response, + Object handler) { + // 线程切换到 customExecutor并回调Restlight + return CompletableFuture.supplyAsync(() -> { + // .... + return true; + }, customExecutor); +} +``` + +其中当执行`HandlerInterceptor.preHandle(xxx)`时用户使用了自定义的线程池作为异步实现，并在完成操作后回调`Restlight`， 后续所有`Controller`, `ExceptionHandler`等操作都将在`customExecutor`的线程上执行（除非用户主动切换） + + + +下面的`Controller`将会在`customExecutor`的线程上被调用， 而不是业务线程池 + +```java +@GetMapping(value = "/test") +public String foo() { + // biz logic + return "Hello Restlight!"; +} +``` + +如果需要回到业务线程池执行则需要用户自行通过`CompletableFuture`进行操作 + +```java +@GetMapping(value = "/test") +public CompletableFuture foo() { + // 回到业务线程池执行Controller逻辑 + return CompletableFuture.supplyAsync(() -> { + // biz logic + return "Hello Restlight!"; + }, bizExecutor); +} +``` \ No newline at end of file diff --git a/docs/Reference_Doc/v0.1.1/async_support/tips_of_completableFuture.md b/docs/Reference_Doc/v0.1.1/async_support/tips_of_completableFuture.md new file mode 100644 index 00000000..b5772740 --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/async_support/tips_of_completableFuture.md @@ -0,0 +1,9 @@ +--- +sort: 2 +--- + +# `CompletableFuture`使用注意 + +- `CompletableFuture`中**不带**`xxxAsync(xxx)`的方法默认会在当前线程执行(当前线程指的是调用`CompletableFuture.complete(xxx)`或者`CompletableFuture.completeExceptionally(xxx)`的线程)， 因此此种方式`CompletableFuture`的线程执行策略为尽量不切换线程（这里的尽量并不是完全一定， 因为如果当前future已经为完成的状态那么`CompletableFuture`会直接执行后续逻辑） +- `CompletableFuture`中**带**`xxxAsync(xxx)`的方法要求传入一个`Executor`， 后续回掉逻辑将在这个`Executor`中执行。 默认不传的情况下会使用`ForkJoinPool`中的公共线程池。 因此应当对所有的`xxxAsync(xxx)`方法调用格外注意， 一旦使用了错误的线程池可能导致隔离性的缺失， 性能不符合预期等问题。 + diff --git a/docs/Reference_Doc/v0.1.1/jaxrs_support/README.md b/docs/Reference_Doc/v0.1.1/jaxrs_support/README.md new file mode 100644 index 00000000..9974edbf --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/jaxrs_support/README.md @@ -0,0 +1,20 @@ +--- +sort: 7 +--- + +# JAX-RS 支持 + +`Restlight`支持了JAX-RS的使用习惯，你可以按照JAX-RS的方式使用Restlight + +引入依赖 + +```xml + + io.esastack + restlight-jaxrs-provider + ${restlight.version} + +``` + +{% include list.liquid all=true %} + diff --git a/docs/Reference_Doc/v0.1.1/jaxrs_support/annotations_support.md b/docs/Reference_Doc/v0.1.1/jaxrs_support/annotations_support.md new file mode 100644 index 00000000..3e6e1b86 --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/jaxrs_support/annotations_support.md @@ -0,0 +1,97 @@ +--- +sort: 1 +--- + +# JAX-RS 注解支持 + +## 支持的注解 + +- `@Path` +- `@GET` +- `@POST` +- `@PUT` +- `@DELETE` +- `@HEAD` +- `@PATCH` +- `@OPTIONS` +- `@Consumes` +- `@Produces` +- `@QueryParam` +- `@PathParam` +- `@HeaderParam` +- `@MatrixParam` +- `@CookieParam` +- `@FormParam` +- `@BeanParam` +- `@DefaultValue` + +```note +现阶段`Restlight`仅实现了`JAX-RS`的注解， 其余功能暂未实现（`Provider`, `Request`, `Response`）等暂不支持 +``` + + +## 注解使用 + +`@QueryParam`, `@PathParam`,`@HeaderParam`,`@MatrixParam`, `@MatrixVariable`,`@FormParam` + +参数绑不支持`javax.ws.rs.ext.ParamConverterProvier`扩展 + +## 个别注解说明 + +### `@QueryParam` + +除普通用法外， 当未指定`value()`或者`name`且参数对象为`Map`类型时， 将整个ParameterMap（即AsyncRequest.getParameterMap）作为参数的值。 + +eg. + +```java +public void foo(@QueryParam Map params) { + //... +} +``` + +```note +除url中的参数之外同时支持Post中Content-Type为application/x-www-form-urlencoded的form表单参数 +``` + +### `@CookieParam` + +普通`String`类型 + +```java +public void foo(@CookieParam String c) { + //... +} +``` + +`Cookie`对象(io.netty.handler.codec.http.cookie.Cookie) + +```java +public void foo(@CookieParam Cookie c) { + //... +} +``` + +获取所有的`Cookie` + +```java +public void foo(@CookieParam Set cookies) { + //... +} +``` + +```note +不支持`JAX-RS`中的`jax.ws.rs.core.Cookie`， 仅支持`io.netty.handler.codec.http.cookie.Cookie` +``` + +### `@HeaderParam` + +除获取单个header之外， 可以如果参数类型为`io.netty.handler.codec.http.HttpHeaders`则以所有的Header作为参数的值 + +eg: + +```java +public void foo(@HeaderParam HttpHeaders headers) { + //... +} +``` diff --git a/docs/Reference_Doc/v0.1.1/quick_start.md b/docs/Reference_Doc/v0.1.1/quick_start.md new file mode 100644 index 00000000..120e0e8b --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/quick_start.md @@ -0,0 +1,42 @@ +# Quick Start + +Create a Spring Boot application and add dependency + +> **Note：`netty` 4.1.56.Final and `tcnative` 2.0.35.Final are directly dependent on.** +s +> **Note: Please make sure the version of `tcnative` matches the version of `netty`.** + + +```xml + + io.esastack + restlight-starter + ${mvn.version} + +``` + +Write your Controller + +```java +@RestController +@SpringBootApplication +public class RestlightDemoApplication { + + @GetMapping("/hello") + public String hello() { + return "Hello Restlight!"; + } + + public static void main(String[] args) { + SpringApplication.run(RestlightDemoApplication.class, args); + } +} +``` + +Run your application and then you would see something like + +``` +Started Restlight server in 1265 millis on 0.0.0.0:8080 +``` + +curl http://localhost:8080/hello diff --git a/docs/Reference_Doc/v0.1.1/restlight_core/README.md b/docs/Reference_Doc/v0.1.1/restlight_core/README.md new file mode 100644 index 00000000..c7d6cdee --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_core/README.md @@ -0,0 +1,33 @@ +--- +sort: 9 +--- + +# Restlight Core + +`esa.restlight.core.Restlight`为`Restlight`架构中的`Restlight Core`模块的入口类， 在`Restlight Server` 基础上丰富了更多的功能 + +- `Controller` +- `ControllerAdvice` +- `HandlerInterceptor`: 拦截器 +- `ExceptionHandler`: 全局异常处理器 +- `BeanValidation`: 参数校验 +- `ArgumentResolver`: 参数解析扩展 +- `ArgumentResolverAdvice`: 参数解析扩展 +- `ReturnValueResolver`: 返回值解析扩展 +- `ReturnValueResolverAdvice`: 返回值解析扩展 +- `RequestSerializer`: 请求序列化器（通常负责反序列化Body内容） +- `ResposneSerializer`: 响应序列化器（通常负责序列化响应对象到Body） +- 内置`Jackson`, `Fastjson`, `Gson`, `ProtoBuf`序列化支持 +- … + +`Restlight Core`在`Restlight Server`中`Route`的业务处理部分做了封装， 完成拦截器，参数绑定，反序列化，返回值解析，序列化等一系列功能。 + +`Restlight Core`为核心实现， 实际使用时需配合`Restlight SpringMVC`以及`Restlight JAX-RS`实现。 + +```tip +`Restlight Core`拥有`Restlight Server`的所有特性， 具体功能特性请参考`Restlight Server`部分 +``` + +由于`Restlight Core`为标准实现， 需要配合`Restlight SpringMVC`或者`Restlight JAX-RS`一起使用 + +{% include list.liquid all=true %} diff --git a/docs/Reference_Doc/v0.1.1/restlight_core/use_jaxrs.md b/docs/Reference_Doc/v0.1.1/restlight_core/use_jaxrs.md new file mode 100644 index 00000000..c6b0570c --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_core/use_jaxrs.md @@ -0,0 +1,56 @@ +--- +sort: 1 +--- + +# 配合 Restlight for JAX-RS使用 + +基于`Restlight Core`为兼容`JAX-RS`注解使用习惯的扩展实现 + +eg. + +引入依赖 + +```xml + + io.esastack + restlight-core + ${restlight.version} + + + io.esastack + restlight-jaxrs-provider + ${restlight.version} + +``` + +编写`Controller` + +```java +@Path("/hello") +public class HelloController { + + @Path("/restlight") + @GET + @Produces(MediaType.TEXT_PLAIN_VALUE) + public String restlight() { + return "Hello Restlight!"; + } +} +``` + +使用`Restlight`启动Server + +```java +Restlight.forServer() + .daemon(false) + .deployments() + .addController(HelloController.class) + .server() + .start(); +``` + +启动并访问： http://localhost:8080/hello 即可看到输出： + +```properties +Hello Restlight! +``` diff --git a/docs/Reference_Doc/v0.1.1/restlight_core/use_springmvc.md b/docs/Reference_Doc/v0.1.1/restlight_core/use_springmvc.md new file mode 100644 index 00000000..303846ab --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_core/use_springmvc.md @@ -0,0 +1,48 @@ +--- +sort: 2 +--- + +# 配合 Restlight for SpringMVC使用 + +```xml + + io.esastack + restlight-core + ${restlight.version} + + + io.esastack + restlight-springmvc-provider + ${restlight.version} + +``` + +编写`Controller` + +```java +@RequestMapping("/hello") +public class HelloController { + + @GetMapping(value = "/restlight") + public String restlight() { + return "Hello Restlight!"; + } +} +``` + +使用`Restlight`启动Server + +```java +Restlight.forServer() + .daemon(false) + .deployments() + .addController(HelloController.class) + .server() + .start(); +``` + +启动并访问： http://localhost:8080/hello 即可看到输出： + +```properties +Hello Restlight! +``` diff --git a/docs/Reference_Doc/v0.1.1/restlight_ext/README.md b/docs/Reference_Doc/v0.1.1/restlight_ext/README.md new file mode 100644 index 00000000..d908f65d --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_ext/README.md @@ -0,0 +1,22 @@ +--- +sort: 4 +--- + +# 扩展能力 + +`Restlight`内置了常用的Filter（IP白名单、新建连接数限制、CPU过载保护）、Interceptor(访问日志、参数签名验证)和表单参数解析器，对应的扩展包分别为： + + +{% include list.liquid all=true %} + +可以一次引入所有扩展能力 + +```xml + + + io.esastack + restlight-ext-starter + ${restlight.version} + +``` + diff --git a/docs/Reference_Doc/v0.1.1/restlight_ext/accesslog.md b/docs/Reference_Doc/v0.1.1/restlight_ext/accesslog.md new file mode 100644 index 00000000..a064f251 --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_ext/accesslog.md @@ -0,0 +1,45 @@ +--- +sort: 3 +--- + +# Access Log + +使用Restlight访问日志拦截器时请确保已经引入了依赖： + +```xml + + io.esastack + restlight-ext-filter-starter + ${restlight.version} + +``` + +## Quick Start + +AccessLog拦截器在每个请求结束后记录访问日志，内容包含：客户端地址、请求协议、请求url（不包含路径参数）、请求方法、请求耗时、响应状态码、响应body大小以及访问时间。使用时需要做如下配置： + +```properties +#开启AccessLog +restlight.server.ext.accesslog.enable=true +``` + +```note +访问日志默认会打印日志到logs/access.log文件中 +``` + +## 配置 + +```note +所有配置均以`restlight.server.ext.accesslog` 开头 +``` + +| 配置项 | 默认 | 说明 | +| ------------ | ---------- | ------------------------------------------------------------ | +| enable | false | 是否启用 | +| directory | logs | 日志文件路径 | +| fileName | access.log | 日志文件名 | +| charset | | 日志编码 | +| rolling | true | 是否按照时间滚动生成文件 | +| date-pattern | yyyy-MM-dd | 日期滚动格式，yyyy-MM-dd表示按天为单位滚动，生成的文件名为access.yyyy-MM-dd.log， 仅支持按天和小时为单位滚动，因此可选值：yyyy-MM-dd或者yyyy-MM-dd_HH（注意不要使用yyyy-MM-dd HH， 生成的文件名可能不符合操作系统文件命名规范） | +| max-history | 10 | 最大历史文件个数 | +| full-uri | false | 是否打印uri中所有的内容（包含url参数） | diff --git a/docs/Reference_Doc/v0.1.1/restlight_ext/connection_creation_limit.md b/docs/Reference_Doc/v0.1.1/restlight_ext/connection_creation_limit.md new file mode 100644 index 00000000..b7e0e5fb --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_ext/connection_creation_limit.md @@ -0,0 +1,26 @@ +--- +sort: 1 +--- + +# 新建连接数限制 + +使用新建连接数限制时请先确保引入了依赖： + +```xml + + io.esastack + restlight-ext-filter-starter + ${restlight.version} + +``` + +当前服务的新建连接数进行QPS限制。超过连接数限制的请求将被拒绝。 + +使用方式： + +```properties +#开启新建连接数限制 +restlight.server.ext.connection-creation-limit.enable=true +#设置每秒限制4000个新建连接,默认为20000 +restlight.server.ext.connection-creation-limit.max-per-second=40000 +``` \ No newline at end of file diff --git a/docs/Reference_Doc/v0.1.1/restlight_ext/cors_origin.md b/docs/Reference_Doc/v0.1.1/restlight_ext/cors_origin.md new file mode 100644 index 00000000..6a515644 --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_ext/cors_origin.md @@ -0,0 +1,37 @@ +--- +sort: 4 +--- + +# 跨域 + +引入依赖 + +```xml + + io.esastack + restlight-ext-filter-starter + ${restlight.version} + +``` + +开启跨域功能 + +```properties +restlight.server.ext.cors.enable=true +``` + +更多跨域相关配置 + +```properties +restlight.server.ext.cors.rules[0].anyOrigin=false +restlight.server.ext.cors.rules[0].origins=www.example.com,www.demo.com +restlight.server.ext.cors.rules[0].expose-headers=foo,bar +restlight.server.ext.cors.rules[0].allow-credentials=false +restlight.server.ext.cors.rules[0].allow-methods=GET,POST +restlight.server.ext.cors.rules[0].allow-headers=foo,bar +restlight.server.ext.cors.rules[0].max-age=3600 +``` + +```note +不配置则应用默认配置 +``` diff --git a/docs/Reference_Doc/v0.1.1/restlight_ext/cpu_load_pretection.md b/docs/Reference_Doc/v0.1.1/restlight_ext/cpu_load_pretection.md new file mode 100644 index 00000000..ffab1140 --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_ext/cpu_load_pretection.md @@ -0,0 +1,38 @@ +--- +sort: 2 +--- + +# CPU Load保护 + +当服务宿主机Cpu负载达到一定阈值之后开始随机丢弃连接（新建连接， 已经建立的连接不受影响）。 + +使用新建连接数限制时请先确保引入了依赖： + +```xml + + io.esastack + restlight-ext-filter-starter + ${restlight.version} + +``` + +```properties +#开启Cpu Load自我保护 +restlight.server.ext.cpu-load-protection.enable=true +#cpu负载阈值，默认为80.0D cpu超过此负载之后将开始随机丢弃连接 +restlight.server.ext.cpu-load-protection.threshold=80.0D +#初始连接丢弃率,默认为10.0D（0代表0%， 100代表100%， 可以传小数） +restlight.server.ext.cpu-load-protection.initial-discard-rate=10.0D +#最大连接丢弃率,默认为80.0D（0代表0%， 100代表100%， 可以传小数） +restlight.server.ext.cpu-load-protection.max-discard-rate=80.0D +``` + +上面的配置将会在cpu负载到达75%时开始随机丢弃20%的新建连接， 随着cpu负载的升高达到100%则将会丢弃80%的连接。 + +说明： + +当cpu负载到达或者超过`cpu-load-threshold`的值时开始丢弃连接，初始连接丢弃概率为`initial-discard-rate`, 随着cpu负载升高， 丢弃率将随着cpu负载的升高而成正比的升高， 当cpu负载达到100%时丢弃率将达到`max-discard-rate`. + +```tip +平滑的连接丢弃比率计算有助于根据cpu使用率的变化来调节连接的丢弃比率。 +``` diff --git a/docs/Reference_Doc/v0.1.1/restlight_ext/data_validate.md b/docs/Reference_Doc/v0.1.1/restlight_ext/data_validate.md new file mode 100644 index 00000000..d728bb6e --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_ext/data_validate.md @@ -0,0 +1,220 @@ +--- +sort: 9 +--- + +# 数据校验 + +Restlight集成了Hibernate Validator，提供了开箱即用的数据校验功能，通过注解完成对JavaBean、Controller方法参数和返回值的校验， 并支持异常消息国际化 。 + +使用Restlight内置的数据校验请先确保引入了依赖： + +```xml + + io.esastack + restlight-ext-validator-starter + ${restlight.version} + +``` + +```note +当前版本的restlight-starter中默认引入了该依赖，使用时无需重复引入 +``` + +## 普通JavaBean的校验 + +使用注解声明对属性的约束 + +```java +private class Employee { + @NotEmpty + private String name; + + @Min(18) + @Max(60) + private int age; + + @Email + private String email; + + @Length(min = 10, max = 20) + private String address; + + // 级联校验 + @Valid + private Object cascadingObject; +} +``` + +作为方法参数校验, 需要使用`@Valid`注解标记被校验的参数 + +```java +@PostMapping("/add") +public String add(@Valid @RequestBody Employee employee) { + return SUCCESS; +} +``` + +作为返回值， 需要使用`@Valid`注解标记方法或者参数 + +```java +@Valid +@ResponseBody +@RequestMapping("/list") +public Employee list1() { + return new Employee("", 16, "", ""); +} +``` + +或者 + +```java +@ResponseBody +@RequestMapping("/list") +public @Valid Employee list2() { + return new Employee("", 16, "", ""); +} +``` + +```note +当需要校验的参数为JavaBean对象时用`@Valid`来显示声明需要对该参数进行校验。 +``` + +## 普通方法参数校验 + +直接使用注解 + +```java +@RequestMapping("/update") +public String update(@RequestParam @NotEmpty String name, @RequestParam @Length(min = 10, max = 20) String newAddress) { + return SUCCESS; +} +``` + +## 分组校验 + +使用`@ValidGroup`指定校验方法的参数、返回值校验时的分组。该注解只能标注在方法上并且value值只能为接口类(默认为`Default.class`)。 + +Example: + +```java +@ValidGroup(Interface.class) +@RequestMapping("/addGroup") +public String addGroup(@Valid @RequestBody Employee employee) { + return SUCCESS; +} +``` + + +## 自定义约束注解 + +当内置的约束注解不能满足业务需求时，可以使用`@Constraint`自定义约束注解，具体实现使用hibernate-validation，使用方式与Spring MVC无差异，示例如下： + +自定义约束注解: + +```java +@Retention(RetentionPolicy.RUNTIME) +@Constraint(validatedBy = LogInSuccess.LogInSuccessValidator.class) +@Target(value = {ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER}) +@Documented +public @interface LogInSuccess { + + String message() default "登录校验未通过"; + + Class[] groups() default {}; + + Class[] payload() default {}; + + class LogInSuccessValidator implements ConstraintValidator { + + @Override + public void initialize(LogInSuccess constraintAnnotation) { + // Do nothing + } + + @Override + public boolean isValid(String value, ConstraintValidatorContext context) { + return false; + } + } +} +``` + +使用自定义约束注解： +```java +@RequestMapping("/getId") +public String getId(@RequestParam @LogInSuccess(message = "请先登录") String userName) { + return "SUCCESS"; +} +``` + +## 国际化 + + +数据校验的异常消息允许自定义并且支持国际化，自定义异常处理消息的步骤如下： + +自定义异常消息文件，在classpath路径下加入配置文件，如validation-message.properties + +```properties +key1=value1 +key2=value2 +... +``` +配置异常消息文件名，在application中配置异常消息文件名，如： + +```properties +#该文件名称对应上面定义的validation-message.properties文件 +restlight.server.ext.validation.message-file=validation-message +``` + +修改约束注解的message属性值，如： + +```java +@NotEmpty(message="{key1}") +public String name; + +@Min(value=18, message="{key2}") +public int age; +``` +针对不同语言定义不同的异常消息文件，如： + +- validation-message_zh_CN.properties +- validation-message_en.properties +- validation-message_cs.properties +- validation-message_en.properties +- ...... + + + +```tip +更多不同语言的文件后缀可以参考jar包：hibernate-validator:5.4.1.Final下ValidationMessage中国际化文件的后缀。 +``` + + + +## 数据校验注解一览 + +| 注解 | 功能 | 说明 | +| --------------------------------------------- | ------------------------------------------------------------ | ----------------- | +| @AssertFalse | 被注解元素必须为false | | +| @AssertTrue | 被注解的元素必须为true | | +| @DecimalMax(value) | 被注解的元素必须为一个数字，其值必须小于等于指定的最小值 | | +| @DecimalMin(Value) | 被注解的元素必须为一个数字，其值必须大于等于指定的最小值 | | +| @Digits(integer=, fraction=) | 被注解的元素必须为一个数字，其值必须在可接受的范围内 | | +| @Future | 被注解的元素必须是未来的日期 | | +| @Max(value) | 被注解的元素必须为一个数字，其值必须小于等于指定的最大值 | | +| @Min(value) | 被注解的元素必须为一个数字，其值必须大于等于指定的最小值 | | +| @NotNull | 被注解的元素必须不为null | | +| @Null | 被注解的元素必须为null | | +| @Past | 被注解的元素必须过去的日期 | | +| @Pattern | 被注解的元素必须符合正则表达式 | | +| @Size(min=, max=) | 被注解的元素必须在指定的范围(数据类型:String, Collection, Map and arrays) | | +| @Email | 被注解的元素被注释的元素必须是电子邮箱地址 | | +| @NotBlank | 被注解的对象必须为字符串，不能为空，检查时会忽略空格 | | +| @NotEmpty | 被注释的对象长度不能为0(数据:String,Collection,Map,arrays) | | +| @Length(min=, max=) | 被注解的对象必须是字符串并且长度必须在指定的范围内 | Hibernate扩展注解 | +| @Range(min=, max=) | 被注释的元素必须在合适的范围内 (数据：BigDecimal, BigInteger, String, byte, short, int, long and 原始类型的包装类 ) | Hibernate扩展注解 | +| @URL(protocol=, host=, port=, regexp=, flags=) | 被注解的对象必须是一个有效的URL，如果提供了protocol，host等，则该URL还需满足提供的条件 | Hibernate扩展注解 | + +```tip +Hibernate扩展注解与javax可能存在注解名重复的情况， 请使用`org.hibernate.xxx`的注解。 +``` diff --git a/docs/Reference_Doc/v0.1.1/restlight_ext/ip_white_list.md b/docs/Reference_Doc/v0.1.1/restlight_ext/ip_white_list.md new file mode 100644 index 00000000..8fe8149a --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_ext/ip_white_list.md @@ -0,0 +1,31 @@ +--- +sort: 8 +--- + +# IP白名单 + +使用Restlight内置的IP白名单时请先确保引入了依赖： + +```xml + + io.esastack + restlight-ext-filter-starter + ${restlight.version} + +``` + +IP白名单拦截器可以过滤非法IP的访问。同时支持IP地址和正则表达式两种匹配方式，需要配置的内容如下： + +```properties +#开启IP白名单拦截器的必需配置 +restlight.server.ext.whitelist.enable=true + +#IP白名单列表（多值请用逗号分隔,正则表达式regex:开头） +restlight.server.ext.whitelist.ips=10.10.1.1,regex:10.12.* + +#缓存最近访问的IP地址（默认1024个） +restlight.server.ext.whitelist.cache-size=1024 + +#缓存的失效时间（单位：ms，默认为60s） +restlight.server.ext.whitelist.expire=60000 +``` \ No newline at end of file diff --git a/docs/Reference_Doc/v0.1.1/restlight_ext/multipart_support.md b/docs/Reference_Doc/v0.1.1/restlight_ext/multipart_support.md new file mode 100644 index 00000000..86e6ae2d --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_ext/multipart_support.md @@ -0,0 +1,79 @@ +--- +sort: 5 +--- + +# 文件及表单参数解析 +`Restlight`提供了表单参数解析的功能，使用时需要单独引入相应的包： + + ```xml + + io.esastack + restlight-ext-multipart-starter + ${restlight.version} + +``` + +## 文件参数 + +使用示例如下： + +```java +@Controller +@RequestMapping("/restlight/file/") +public class FileSupportController + // 上传单个文件 + @RequestMapping("/upload") + public String fileUpload(@UploadFile MultipartFile multipartFile) throws IOException { + File temp = new File("D:\\" + multipartFile.getOriginalFilename()); + multipartFile.transferTo(temp); + return "SUCCESS"; + } + + // 上传一组文件 + @RequestMapping("/uploads") + public String fileUploads(@UploadFile List files) throws IOException { + for (MultipartFile file : files) { + File temp = new File("D:\\" + file.getOriginalFilename()); + file.transferTo(temp); + } + return "SUCCESS"; + } +} +``` + +```warning +对于超大文件的上传可能会导致OOM，因为Restlight底层基于Netty实现，会将整个请求body转换成byte[]数组存放在内存中，再将对应的数据转成文件格式。 +``` + +`Restlight`默认请求body大小为4MB，当上传文件时需要根据需要调整该值的大小；默认的编码格式为：UTF-8。使用时，也可以通过配置文件改变上述参数值： + +```properties +#设置请求body大小 4MB = 4 * 1024 * 1024 = 4194304 +restlight.server.max-content-length=4194304 + +#编码方式 +restlight.server.ext.multipart.charset=utf-8 + +#单个文件大小限制，默认-1（没有限制） 4KB = 4 * 1024 = 4096 +restlight.server.ext.multipart.max-size=4096 + +#是否使用临时文件，为true时任何大小的文件都使用临时文件，默认为false +restlight.server.ext.multipart.use-disk=true + +#临时文件目录 +restlight.server.ext.multipart.temp-dir=D:\\temp + +#当multipart-use-disk为false且单个文件大小超过该值时使用临时文件，默认2MB +restlight.server.ext.multipart.memory-threshold=2097152 +``` + +### 非文件参数 + +在需要接收的方法参数上加上`@FormParam`注解，如下： + +```java +@RequestMapping("/upload") +public String uploadFormParams(@FormParam String formParam0, @FormParam String formParam1) { + return formParam0 + "; " + formParam1; +} +``` \ No newline at end of file diff --git a/docs/Reference_Doc/v0.1.1/restlight_ext/signature_validation.md b/docs/Reference_Doc/v0.1.1/restlight_ext/signature_validation.md new file mode 100644 index 00000000..ae98427f --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_ext/signature_validation.md @@ -0,0 +1,114 @@ +--- +sort: 6 +--- + +# 签名认证 + +使用Restlight参数签名验证拦截器时请先引入依赖： + +```xml + + io.esastack + restlight-ext-interceptor-starter + ${restlight.version} + +``` + +参数签名验证拦截器可以验证请求参数的签名，防止请求参数被篡改。使用时请做如下配置： + +```properties +#开启参数签名验证功能的必需配置 +restlight.server.ext.sign.enable=true + +#调用方ID参数名,默认为appId +restlight.server.ext.sign.app-id-name=appId + +#签名秘钥版本参数名,默认为sv +restlight.server.ext.sign.secret-version-name=sv + +#请求时间戳参数名,默认为ts +restlight.server.ext.sign.timestamp-name=ts + +#请求时间戳有效期：单位秒（默认为0） +restlight.server.ext.sign.expire-seconds=0 + +#签名参数名称,默认为sign +restlight.server.ext.sign.signature-name=sign + +#是否对所有接口进行签名验证（默认为false） +restlight.server.ext.sign.verify-all=true +``` + +```note +配置完成后，需要自定义esa.restlight.ext.interceptor.signature.SecretProvider的实现类并注入Spring容器。该接口定义了通过appId、secretVersion、timestamp获取秘钥的方法。 +``` + +## 服务端验签详细过程 +- 第一步：从请求中获取签名值signature并去掉前后空格（先从url参数中获取，如果没有再从请求头中获取）； +- 第二步：从请求中获取时间戳timestamp并去掉前后空格（方式同上），如果配置了请求时间戳有效期，则判断是否在有效期内。 +- 第三步：从请求中获取appId、secretVersion并去掉前后空格（方式同上）。 +- 第四步：根据上述的appId、secretVersion、timestamp从自定义的SecretProvider获取secret。 +- 第五步：根据请求参数构建签名data[]，具体步骤为：1.构建请求参数对应的paramData[]：获取所有的url参数（排除sign），按照参数名字典序升序排列，若一个参数对应多个值，则这多个值也按字典序升序排列（**注意：所有参数名和参数值均会去掉前后空格**）。如：http://api.xxx.com/getUserInfo?appId=your_appId&sv=1&ts=1555933697000&user_id=u001&sign=xxx&names=LiMing&names=ZhangSan对应的paramData[]=("api_key=your_appId&names=LiMing&names=ZhangSan&sv=1&t=1555933697000&user_id=u001").getBytes("UTF-8")；2.构建请求body对应的bodyData[]：对于类型为POST且Content-Type不包含x-www-form-urlencoded的请求，直接通过request.getBody()获取bodyData[]。**重要说明：** 对于Content-Type包含x-www-form-urlencoded的POST请求，验证签名时会将body中参数合并到url的参数中一起处理，客户端加密时需要注意此种情况；3.合并paramData[]和bodyData[]作为签名data[]。 +- 第六步：使用HmacSha1算法生成data[]与secret的签名（详见esa-commons项目下SecurityUtils的getHmacSHA1方法）。 +- 第七步：验证signature与第六步生成的签名是否相等。 + +```note +参数签名验证失败会抛出SignatureValidationException，该异常的message中保存了验签失败的详细原因，使用时可根据需要自定义该异常的处理方法 +Restlight已在内部开源，签名验证的代码实现参见：restlight-support模块下AbstractSignatureInterceptor。 +``` + +## 指定或排除需要进行签名验证的接口 +Restlight提供了两种不同的方式来自定义需要进行签名验证的接口：1. 在全局接口都进行签名验证的情况下，使用@IgnoreSignValidation注解忽略指定接口的签名验证功能；2. 在全局接口都不进行签名验证的前提下，使用@SignValidation注解指定对需要进行签名验证的接口。默认使用方式2。 +方式1使用示例： + +```properties +restlight.server.ext.sign.verify-all=true +``` + +```java +@RequestMapping("/index") +@IgnoreSignValidation +public void index() { + TestService.list(); +} +``` + +如上配置表示：对index()方法之外的其他接口均开启签名验证功能。 + +方式2使用示例： + +``` +restlight.server.ext.sign.verify-all=false +``` + +```java +@RequestMapping("/index") +@SignValidation +public void index() { + TestService.list(); +} +``` + +如上配置表示：只对index()方法对应的接口开启签名验证功能。 + +### 自定义参数签名验证拦截器 +`Restlight`默认使用**HmacSHA1**作为验签时原始请求的签名生成方法，当用户使用其它算法可以注入自定义的参数签名验证拦截器，使用示例如下： +```java +@Component +public class CustomizeSignatureValidationFactory extends SignValidationHandlerInterceptorFactory { + + public CustomizeSignatureValidationFactory(SecretDistributor distributor) { + super(distributor); + } + + @Override + protected AbstractSignatureRouteInterceptor doCreate(SignatureOptions options, SecretDistributor distributor) { + return new AbstractSignatureRouteInterceptor(options, distributor) { + @Override + protected boolean validate(byte[] data, String signature, String sk) { + // customize validation + } + }; + } +} +``` \ No newline at end of file diff --git a/docs/Reference_Doc/v0.1.1/restlight_ext/xss_support.md b/docs/Reference_Doc/v0.1.1/restlight_ext/xss_support.md new file mode 100644 index 00000000..98d0052e --- /dev/null +++ b/docs/Reference_Doc/v0.1.1/restlight_ext/xss_support.md @@ -0,0 +1,63 @@ +--- +sort: 7 +--- + +# XSS过滤 + +引入依赖： + +```xml + + io.esastack + restlight-ext-filter-starter + ${restlight.version} + +``` + +使用方式： +```properties +#开启Xss过滤 +restlight.server.ext.xss.enable=true +#Xss过滤模式，默认escape（转义模式），filter为过滤模式 +restlight.server.ext.xss.mode=escape +``` +配置好后自动对所有请求进行转义或者过滤。 + +## XSS过滤范围 + +支持`URL`参数过滤及**不完整**的`Header`过滤 + +```note +Header相关参数仅支持`AsyncRequest.getHeader(CharSequence name)`以及`AsyncRequest.getHeader(String name)`方法。 +``` + +## `Escape` & `Filter`模式 + +### `Escape` 模式 + +该模式会对用户请求的 `URL`参数 和 `Header `进行转义，转义的字符集如下： + +|转义前|转义后| +|-|-| +|>|\>| +|<|\<| +|"|\"| +|&|\&| + +### `Filter` 模式 + +该模式会对用户请求的 `URL`参数 和 `Header `进行过滤，删除容易引起 Xss 的标签或者表达式，以空串代替，比如 `name=` ，过滤以后会直接将 `` 以空串替换，即 `name=""`，需要以空串替换的标签和表达式如下： + +| 标签或表达式 | +| ---------------------- | +| \ | +| \ | +| \