<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<link rel="icon" href="https://avatars0.githubusercontent.com/u/58360786?s=200&v=4" title="Kayrx">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.10.2/dist/katex.min.css" integrity="sha384-yFRtMMDnQtDRO8rLpMIKrtPCD5jdktao2TV19YiZYWMDkUR5GQZR/NOVTdquEx1j" crossorigin="anonymous">
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/katex-copytex@latest/dist/katex-copytex.min.css">
<script src="https://cdn.jsdelivr.net/npm/katex-copytex@latest/dist/katex-copytex.min.js"></script>
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/Microsoft/vscode/extensions/markdown-language-features/media/markdown.css">
<link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/gh/Microsoft/vscode/extensions/markdown-language-features/media/highlight.css">
<link rel="stylesheet" type="text/css" href="https://kayrx.xyz/home.css" />
<title>Kayrx / app</title>
</head>
<body class="vscode-light">
<div id="page" class="page-section-doc">
<div id="mnav">
<div id="lnav">
<div id="left">
<a id="front" href="/"><img src="/kayrx.png"/></a>
<span id="dlnav">
<a class="tail" href="/kayrx/" >Kayrx</a>
<a class="tail" href="/yarx" >Yarx</a>
<a class="tail" href="/blog" >Blog</a>
</span>
</div>
<label ><a href="#" id="menu">M</a></label>
</div>
<div id="rnav">
<li > <a href="https://spectrum.chat/kayrx" target="_black" style="color:green; font-weight: bold;" >群聊</a></li>
<li ><a href="/community" >社区</a></li>
<li > <a href="/funding">赞助</a></li>
</div>
</div>
<div id="content">
<div class="container"><div class="doc-page doc-section-basic-app">
<div class="doc-nav">
<details id="pc" open>
<summary id="dir"><strong>目录指南</strong></summary>
<details open>
<summary id="title"><strong>介绍</strong></summary>
<a class="doc-section-link-introduction-index" href="/kayrx/introduction/index.html">欢迎</a>
<a class="doc-section-link-introduction-whatis" href="/kayrx/introduction/whatis.html">何为Actix</a>
<a class="doc-section-link-introduction-install" href="/kayrx/introduction/install.html">安装</a>
</details>
<details open>
<summary id="title"><strong>基本</strong></summary>
<a class="doc-section-link-basic-start" href="/kayrx/basic/start.html">入门</a>
<a class="doc-section-link-basic-app" href="/kayrx/basic/app.html">应用</a>
<a class="doc-section-link-basic-server" href="/kayrx/basic/server.html">服务器</a>
<a class="doc-section-link-basic-handler" href="/kayrx/basic/handler.html">处理器</a>
<a class="doc-section-link-basic-extractor" href="/kayrx/basic/extractor.html">提取器</a>
</details>
<details open>
<summary id="title"><strong>高级</strong></summary>
<a class="doc-section-link-advance-error" href="/kayrx/advance/error.html">错误</a>
<a class="doc-section-link-advance-url-dispatch" href="/kayrx/advance/url-dispatch.html">路由分发</a>
<a class="doc-section-link-advance-request" href="/kayrx/advance/request.html">请求</a>
<a class="doc-section-link-advance-response" href="/kayrx/advance/response.html">响应</a>
<a class="doc-section-link-advance-test" href="/kayrx/advance/test.html">测试</a>
<a class="doc-section-link-advance-middleware" href="/kayrx/advance/middleware.html">中间件</a>
<a class="doc-section-link-advance-static-file" href="/kayrx/advance/static-file.html">静态文件</a>
</details>
<details open>
<summary id="title"><strong>协议</strong></summary>
<a class="doc-section-link-protocol-websocket" href="/kayrx/protocol/websocket.html">Websocket</a>
<a class="doc-section-link-protocol-http2" href="/kayrx/protocol/http2.html">HTTP2</a>
</details>
<details open>
<summary id="title"><strong>模式</strong></summary>
<a class="doc-section-link-pattern-autoreload" href="/kayrx/pattern/autoreload.html">自动重载</a>
<a class="doc-section-link-pattern-database" href="/kayrx/pattern/database.html">数据库</a>
</details>
</details>
<details id="mobile">
<summary id="dir"><strong>目录指南</strong></summary>
<details open>
<summary id="title"><strong>介绍</strong></summary>
<a class="doc-section-link-introduction-index" href="/kayrx/introduction/index.html">欢迎</a>
<a class="doc-section-link-introduction-whatis" href="/kayrx/introduction/whatis.html">何为Actix</a>
<a class="doc-section-link-introduction-install" href="/kayrx/introduction/install.html">安装</a>
</details>
<details open>
<summary id="title"><strong>基本</strong></summary>
<a class="doc-section-link-basic-start" href="/kayrx/basic/start.html">入门</a>
<a class="doc-section-link-basic-app" href="/kayrx/basic/app.html">应用</a>
<a class="doc-section-link-basic-server" href="/kayrx/basic/server.html">服务器</a>
<a class="doc-section-link-basic-handler" href="/kayrx/basic/handler.html">处理器</a>
<a class="doc-section-link-basic-extractor" href="/kayrx/basic/extractor.html">提取器</a>
</details>
<details open>
<summary id="title"><strong>高级</strong></summary>
<a class="doc-section-link-advance-error" href="/kayrx/advance/error.html">错误</a>
<a class="doc-section-link-advance-url-dispatch" href="/kayrx/advance/url-dispatch.html">路由分发</a>
<a class="doc-section-link-advance-request" href="/kayrx/advance/request.html">请求</a>
<a class="doc-section-link-advance-response" href="/kayrx/advance/response.html">响应</a>
<a class="doc-section-link-advance-test" href="/kayrx/advance/test.html">测试</a>
<a class="doc-section-link-advance-middleware" href="/kayrx/advance/middleware.html">中间件</a>
<a class="doc-section-link-advance-static-file" href="/kayrx/advance/static-file.html">静态文件</a>
</details>
<details open>
<summary id="title"><strong>协议</strong></summary>
<a class="doc-section-link-protocol-websocket" href="/kayrx/protocol/websocket.html">Websocket</a>
<a class="doc-section-link-protocol-http2" href="/kayrx/protocol/http2.html">HTTP2</a>
</details>
<details open>
<summary id="title"><strong>模式</strong></summary>
<a class="doc-section-link-pattern-autoreload" href="/kayrx/pattern/autoreload.html">自动重载</a>
<a class="doc-section-link-pattern-database" href="/kayrx/pattern/database.html">数据库</a>
</details>
</details>
</div>
<div class="doc-content"> <h1 id="writing-an-application">Writing an Application</h1>
<p><code>actix-web</code> provides various primitives to build web servers and applications with Rust.
It provides routing, middlewares, pre-processing of requests, post-processing of
responses, etc.</p>
<p>All <code>actix-web</code> servers are built around the <a href="https://docs.rs/actix-web/2/actix_web/struct.App.html"><code>App</code></a> instance. It is used for
registering routes for resources and middlewares. It also stores application
state shared across all handlers within same scope.</p>
<p>An application's <a href="https://docs.rs/actix-web/2/actix_web/struct.Scope.html"><code>scope</code></a> acts as a namespace for all routes, i.e. all routes for a
specific application scope have the same url path prefix. The application prefix always
contains a leading "/" slash. If a supplied prefix does not contain leading slash,
it is automatically inserted. The prefix should consist of value path segments.</p>
<blockquote>
<p>For an application with scope <code>/app</code>,
any request with the paths <code>/app</code>, <code>/app/</code>, or <code>/app/test</code> would match;
however, the path <code>/application</code> would not match.</p>
</blockquote>
<p>{{< include-example example="application" file="<a href="http://app.rs">app.rs</a>" section="setup" >}}</p>
<p>In this example, an application with the <code>/app</code> prefix and a <code>index.html</code> resource
are created. This resource is available through the <code>/app/index.html</code> url.</p>
<blockquote>
<p>For more information, check the <a href="/docs/url-dispatch/index.html#using-an-application-prefix-to-compose-applications">URL Dispatch</a> section.</p>
</blockquote>
<h2 id="state">State</h2>
<p>Application state is shared with all routes and resources within the same scope. State
can be accessed with the <a href="https://docs.rs/actix-web/2/actix_web/web/struct.Data.html"><code>web::Data<T></code></a> extractor where <code>T</code> is type of state. State is
also available for middlewares.</p>
<p>Let's write a simple application and store the application name in the state:</p>
<p>{{< include-example example="application" file="<a href="http://state.rs">state.rs</a>" section="setup" >}}</p>
<p>and pass in the state when initializing the App, and start the application:</p>
<p>{{< include-example example="application" file="<a href="http://state.rs">state.rs</a>" section="start_app" >}}</p>
<p>Any number of state types could be registered within application.</p>
<h2 id="shared-mutable-state">Shared Mutable State</h2>
<p><code>HttpServer</code> accepts an application factory rather than an application instance.
Http server constructs an application instance for each thread, thus application data must be
constructed multiple times. If you want to share data between different threads, a shareable
object should be used, e.g. Send + Sync.</p>
<p>Internally, <a href="https://docs.rs/actix-web/2/actix_web/web/struct.Data.html"><code>web::Data</code></a> uses Arc. Thus, in order to avoid double Arc, we should create our Data before registering it using <a href="https://docs.rs/actix-web/2/actix_web/struct.App.html#method.app_data"><code>App::app_data()</code></a>.</p>
<p>In the following example, we will write an application with mutable, shared state. First, we define our state and create our handler:</p>
<p>{{< include-example example="application" file="<a href="http://state.rs">state.rs</a>" section="setup_mutable" >}}</p>
<p>and register the data in an App:</p>
<p>{{< include-example example="application" file="<a href="http://state.rs">state.rs</a>" section="make_app_mutable" >}}</p>
<h2 id="using-an-application-scope-to-compose-applications">Using an Application Scope to Compose Applications</h2>
<p>The <a href="https://docs.rs/actix-web/2/actix_web/web/fn.scope.html"><code>web::scope()</code></a> method allows to set a specific application prefix. This scope represents
a resource prefix that will be prepended to all resource patterns added by the resource
configuration. This can be used to help mount a set of routes at a different location
than the included callable's author intended while still maintaining the same resource names.</p>
<p>For example:</p>
<p>{{< include-example example="application" file="<a href="http://scope.rs">scope.rs</a>" section="scope" >}}</p>
<p>In the above example, the <em>show_users</em> route will have an effective route pattern of
<em>/users/show</em> instead of <em>/show</em> because the application's scope argument will be prepended
to the pattern. The route will then only match if the URL path is <em>/users/show</em>,
and when the <a href="https://docs.rs/actix-web/2/actix_web/struct.HttpRequest.html#method.url_for"><code>HttpRequest.url_for()</code></a> function is called with the route name show_users,
it will generate a URL with that same path.</p>
<h2 id="application-guards-and-virtual-hosting">Application guards and virtual hosting</h2>
<p>You can think of a guard as a simple function that accepts a <em>request</em> object reference
and returns <em>true</em> or <em>false</em>. Formally, a guard is any object that implements the
<a href="https://docs.rs/actix-web/2/actix_web/guard/trait.Guard.html"><code>Guard</code></a> trait. Actix-web provides several guards, you can check
<a href="https://docs.rs/actix-web/2/actix_web/guard/index.html#functions">functions section</a> of api docs.</p>
<p>One of the provided guards is <a href="https://docs.rs/actix-web/2/actix_web/guard/fn.Header.html"><code>Header</code></a>, it can be used as application's
filter based on request's header information.</p>
<p>{{< include-example example="application" file="<a href="http://vh.rs">vh.rs</a>" section="vh" >}}</p>
<h1 id="configure">Configure</h1>
<p>For simplicity and reusability both <a href="https://docs.rs/actix-web/2/actix_web/struct.App.html#method.configure"><code>App</code></a> and <a href="https://docs.rs/actix-web/2/actix_web/struct.Scope.html#method.configure"><code>web::Scope</code></a> provide the <code>configure</code> method.
This function is useful for moving parts of configuration to a different module or even
library. For example, some of the resource's configuration could be moved to different
module.</p>
<p>{{< include-example example="application" file="<a href="http://config.rs">config.rs</a>" section="config" >}}</p>
<p>The result of the above example would be:</p>
<pre><code><code><div>/ -> "/"
/app -> "app"
/api/test -> "test"
</div></code></code></pre>
<p>Each <code>ServiceConfig</code> can have it's own <code>data</code>, <code>routes</code>, and <code>services</code></p>
<p>It is also possible to create application object in separate function.
<code>App</code> type uses complex generics and result type have to use <code>impl Trait</code> feature.
This could be useful for unit tests.</p>
<p>{{< include-example example="application" file="config_app.rs" section="config" >}}</p>
</div>
</div>
</div>
</div>
<div id="footer">
© 2019 <a href="https://github.com/kayrx">Kayrx</a>
</div>
</div>
<script async>
window.onload = function() {
let menu = document.getElementById('menu');
menu.addEventListener('click', function() {
let nav = document.getElementById('rnav');
if (nav.style.height == 'auto') {
nav.style.height = '0';
}else{
nav.style.height = 'auto';
}
}, false)
}
</script>
</body>
</html>