<!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 / extractor</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-extractor">
<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="type-safe-information-extraction">Type-safe information extraction</h1>
<p>Actix-web provides a facility for type-safe request information access called <em>extractors</em>
(ie, <code>impl FromRequest</code>). By default, actix-web provides several extractor implementations.</p>
<p>An extractor can be accessed as an arguments to a handler function. Actix-web supports
up to 10 extractors per handler function. Argument position does not matter.</p>
<p>{{< include-example example="extractors" file="<a href="http://main.rs">main.rs</a>" section="option-one" >}}</p>
<h1 id="path">Path</h1>
<p><a href="https://docs.rs/actix-web/2/actix_web/dev/struct.Path.html"><em>Path</em></a> provides information that can be extracted from the Request's
path. You can deserialize any variable segment from the path.</p>
<p>For instance, for resource that registered for the <code>/users/{userid}/{friend}</code> path
two segments could be deserialized, <code>userid</code> and <code>friend</code>. These segments could be
extracted into a <code>tuple</code>, i.e. <code>Path<(u32, String)></code> or any structure that implements
the <code>Deserialize</code> trait from the <em>serde</em> crate.</p>
<p>{{< include-example example="extractors" file="path_one.rs" section="path-one" >}}</p>
<p>It is also possible to extract path information to a specific type that implements the
<code>Deserialize</code> trait from <em>serde</em>. Here is an equivalent example that uses <em>serde</em>
instead of a <em>tuple</em> type.</p>
<p>{{< include-example example="extractors" file="path_two.rs" section="path-two" >}}</p>
<p>It is also possible to <code>get</code> or <code>query</code> the request for path parameters by name:</p>
<p>{{< include-example example="extractors" file="path_three.rs" section="path-three" >}}</p>
<h1 id="query">Query</h1>
<p>The <a href="https://docs.rs/actix-web/2/actix_web/web/struct.Query.html"><em>Query</em></a> type provides extraction functionality for the request's
query parameters. Underneath it uses <em>serde_urlencoded</em> crate.</p>
<p>{{< include-example example="extractors" file="<a href="http://query.rs">query.rs</a>" section="query" >}}</p>
<h1 id="json">Json</h1>
<p><a href="https://docs.rs/actix-web/2/actix_web/web/struct.Json.html"><em>Json</em></a> allows to deserialize a request body into a struct. To extract
typed information from a request's body, the type <code>T</code> must implement the <code>Deserialize</code>
trait from <em>serde</em>.</p>
<p>{{< include-example example="extractors" file="json_one.rs" section="json-one" >}}</p>
<p>Some extractors provide a way to configure the extraction process. Json extractor
<a href="https://docs.rs/actix-web/2/actix_web/web/struct.JsonConfig.html"><em>JsonConfig</em></a> type for configuration. To configure an extractor, pass it's
configuration object to the resource's <code>.data()</code> method. In case of a <em>Json</em> extractor
it returns a <em>JsonConfig</em>. You can configure the maximum size of the json payload as
well as a custom error handler function.</p>
<p>The following example limits the size of the payload to 4kb and uses a custom error handler.</p>
<p>{{< include-example example="extractors" file="json_two.rs" section="json-two" >}}</p>
<h1 id="form">Form</h1>
<p>At the moment only url-encoded forms are supported. The url-encoded body could be
extracted to a specific type. This type must implement the <code>Deserialize</code> trait from
the <em>serde</em> crate.</p>
<p><a href="https://docs.rs/actix-web/2/actix_web/web/struct.FormConfig.html"><em>FormConfig</em></a> allows configuring the extraction process.</p>
<p>{{< include-example example="extractors" file="<a href="http://form.rs">form.rs</a>" section="form" >}}</p>
<h1 id="other">Other</h1>
<p>Actix-web also provides several other extractors:</p>
<ul>
<li><a href="https://docs.rs/actix-web/2/actix_web/web/struct.Data.html"><em>Data</em></a> - If you need access to an application state.</li>
<li><em>HttpRequest</em> - <em>HttpRequest</em> itself is an extractor which returns self, in case you
need access to the request.</li>
<li><em>String</em> - You can convert a request's payload to a <em>String</em>. <a href="https://docs.rs/actix-web/2/actix_web/trait.FromRequest.html#example-2"><em>Example</em></a>
is available in doc strings.</li>
<li><em>bytes::Bytes</em> - You can convert a request's payload into <em>Bytes</em>.
<a href="https://docs.rs/actix-web/2/actix_web/trait.FromRequest.html#example-4"><em>Example</em></a>
is available in doc strings.</li>
<li><em>Payload</em> - You can access a request's payload.
<a href="https://docs.rs/actix-web/2/actix_web/web/struct.Payload.html"><em>Example</em></a></li>
</ul>
<h1 id="application-state-extractor">Application state extractor</h1>
<p>Application state is accessible from the handler with the <code>web::Data</code> extractor;
however, state is accessible as a read-only reference. If you need mutable access to state,
it must be implemented.</p>
<blockquote>
<p><strong>Beware</strong>, actix creates multiple copies of the application state and the handlers,
unique for each thread. If you run your application in several threads, actix will
create the same amount as number of threads of application state objects and handler
objects.</p>
</blockquote>
<p>Here is an example of a handler that stores the number of processed requests:</p>
<p>{{< include-example example="request-handlers" file="<a href="http://main.rs">main.rs</a>" section="data" >}}</p>
<p>Although this handler will work, <code>self.0</code> will be different depending on the number of threads and
number of requests processed per thread. A proper implementation would use <code>Arc</code> and <code>AtomicUsize</code>.</p>
<p>{{< include-example example="request-handlers" file="handlers_arc.rs" section="arc" >}}</p>
<blockquote>
<p>Be careful with synchronization primitives like <code>Mutex</code> or <code>RwLock</code>. The <code>actix-web</code> framework
handles requests asynchronously. By blocking thread execution, all concurrent
request handling processes would block. If you need to share or update some state
from multiple threads, consider using the tokio synchronization primitives.</p>
</blockquote>
</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>