github.com/System-Glitch/goyave/v2@v2.10.3-0.20200819142921-51011e75d504/docs/guide/advanced/status-handlers.html (about)

     1  <!DOCTYPE html>
     2  <html lang="en-US">
     3    <head>
     4      <meta charset="utf-8">
     5      <meta name="viewport" content="width=device-width,initial-scale=1">
     6      <title>Status Handlers | Goyave</title>
     7      <meta name="generator" content="VuePress 1.5.3">
     8      <link rel="icon" type="image/png" sizes="16x16" href="/goyave/goyave_16.png">
     9      <link rel="icon" type="image/png" sizes="32x32" href="/goyave/goyave_32.png">
    10      <link rel="icon" type="image/png" sizes="64x64" href="/goyave/goyave_64.png">
    11      <link rel="icon" type="image/png" sizes="128x128" href="/goyave/goyave_128.png">
    12      <link rel="icon" type="image/png" sizes="256x256" href="/goyave/goyave_256.png">
    13      <link rel="icon" type="image/png" sizes="512x512" href="/goyave/goyave_512.png">
    14      <meta name="description" content="Goyave is a Golang web API framework aiming at cleanliness, fast development and power.">
    15      <meta name="og:title" content="Status Handlers - Goyave">
    16      <meta name="twitter:title" content="Status Handlers - Goyave">
    17      <meta name="title" content="Status Handlers - Goyave">
    18      <meta property="twitter:description" content="Goyave is a Golang web API framework aiming at cleanliness, fast development and power.">
    19      <meta property="twitter:image:src" content="https://system-glitch.github.io/goyave/goyave_banner.png">
    20      <meta property="twitter:card" content="summary_large_image">
    21      <meta property="og:type" content="website">
    22      <meta property="og:description" content="Goyave is a Golang web API framework aiming at cleanliness, fast development and power.">
    23      <meta property="og:image" content="https://system-glitch.github.io/goyave/goyave_banner.png">
    24      <meta property="og:site_name" content="Goyave">
    25      <link rel="preload" href="/goyave/assets/css/0.styles.589fd562.css" as="style"><link rel="preload" href="/goyave/assets/js/app.092490a7.js" as="script"><link rel="preload" href="/goyave/assets/js/4.75a9cc68.js" as="script"><link rel="preload" href="/goyave/assets/js/1.121dd9ed.js" as="script"><link rel="preload" href="/goyave/assets/js/14.b933d8cf.js" as="script"><link rel="preload" href="/goyave/assets/js/5.c83f1192.js" as="script"><link rel="prefetch" href="/goyave/assets/js/10.2f07bbf5.js"><link rel="prefetch" href="/goyave/assets/js/11.2d66fdef.js"><link rel="prefetch" href="/goyave/assets/js/12.63171b15.js"><link rel="prefetch" href="/goyave/assets/js/13.770050f3.js"><link rel="prefetch" href="/goyave/assets/js/15.36df2a66.js"><link rel="prefetch" href="/goyave/assets/js/16.ed66719e.js"><link rel="prefetch" href="/goyave/assets/js/17.7bef5f05.js"><link rel="prefetch" href="/goyave/assets/js/18.470b55ed.js"><link rel="prefetch" href="/goyave/assets/js/19.90e0dab8.js"><link rel="prefetch" href="/goyave/assets/js/20.3a300ca3.js"><link rel="prefetch" href="/goyave/assets/js/21.c3fd6053.js"><link rel="prefetch" href="/goyave/assets/js/22.d5569617.js"><link rel="prefetch" href="/goyave/assets/js/23.931b2034.js"><link rel="prefetch" href="/goyave/assets/js/24.1a4755e7.js"><link rel="prefetch" href="/goyave/assets/js/25.0d463913.js"><link rel="prefetch" href="/goyave/assets/js/26.3c173a7a.js"><link rel="prefetch" href="/goyave/assets/js/27.9c5b36f2.js"><link rel="prefetch" href="/goyave/assets/js/28.41e055b7.js"><link rel="prefetch" href="/goyave/assets/js/29.b87adf4a.js"><link rel="prefetch" href="/goyave/assets/js/3.ef71e77d.js"><link rel="prefetch" href="/goyave/assets/js/6.2336bf0c.js"><link rel="prefetch" href="/goyave/assets/js/7.d60e55c1.js"><link rel="prefetch" href="/goyave/assets/js/8.2ee33a42.js"><link rel="prefetch" href="/goyave/assets/js/9.8e043d60.js">
    26      <link rel="stylesheet" href="/goyave/assets/css/0.styles.589fd562.css">
    27    </head>
    28    <body>
    29      <div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/goyave/" class="home-link router-link-active"><img src="/goyave/goyave_64.png" alt="Goyave" class="logo"> <span class="site-name can-hide">Goyave</span></a> <div class="links"><div class="user-settings"><a title="Dark theme" href="#" class="settings-button"><svg aria-hidden="true" data-prefix="fas" data-icon="cog" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" class="svg-inline--fa fa-cog fa-w-16 settings-icon"><path fill="currentColor" d="M8 0c-4.4 0-8 3.6-8 8s3.6 8 8 8 8-3.6 8-8-3.6-8-8-8zM8 15c-3.9 0-7-3.1-7-7 0-2.4 1.2-4.6 3.2-5.9-0.1 0.6-0.2 1.3-0.2 1.9 0 4.9 4 8.9 8.9 9-1.3 1.3-3 2-4.9 2z"></path></svg></a></div> <div class="search-box"><input aria-label="Search" autocomplete="off" spellcheck="false" value=""> <!----></div> <nav class="nav-links can-hide"><div class="nav-item"><a href="/goyave/guide/" class="nav-link router-link-active">
    30    Guide
    31  </a></div><div class="nav-item"><a href="https://pkg.go.dev/github.com/System-Glitch/goyave/v2" target="_blank" rel="noopener noreferrer" class="nav-link external">
    32    pkg.go.dev
    33    <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></div> <a href="https://github.com/System-Glitch/goyave" target="_blank" rel="noopener noreferrer" class="repo-link">
    34      GitHub
    35      <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"><div class="nav-item"><a href="/goyave/guide/" class="nav-link router-link-active">
    36    Guide
    37  </a></div><div class="nav-item"><a href="https://pkg.go.dev/github.com/System-Glitch/goyave/v2" target="_blank" rel="noopener noreferrer" class="nav-link external">
    38    pkg.go.dev
    39    <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></div> <a href="https://github.com/System-Glitch/goyave" target="_blank" rel="noopener noreferrer" class="repo-link">
    40      GitHub
    41      <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></a></nav>  <ul class="sidebar-links"><li><section class="sidebar-group collapsable depth-0"><p class="sidebar-heading"><span>Guide</span> <span class="arrow right"></span></p> <!----></section></li><li><section class="sidebar-group collapsable depth-0"><p class="sidebar-heading"><span>The Basics</span> <span class="arrow right"></span></p> <!----></section></li><li><section class="sidebar-group collapsable depth-0"><p class="sidebar-heading open"><span>Advanced</span> <span class="arrow down"></span></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/goyave/guide/advanced/helpers.html" class="sidebar-link">Helpers</a></li><li><a href="/goyave/guide/advanced/authentication.html" class="sidebar-link">Authentication</a></li><li><a href="/goyave/guide/advanced/localization.html" class="sidebar-link">Localization</a></li><li><a href="/goyave/guide/advanced/testing.html" class="sidebar-link">Testing</a></li><li><a href="/goyave/guide/advanced/multi-services.html" class="sidebar-link">Multi-services</a></li><li><a href="/goyave/guide/advanced/cors.html" class="sidebar-link">CORS</a></li><li><a href="/goyave/guide/advanced/status-handlers.html" aria-current="page" class="active sidebar-link">Status Handlers</a><ul class="sidebar-sub-headers"><li class="sidebar-sub-header"><a href="/goyave/guide/advanced/status-handlers.html#introduction" class="sidebar-link">Introduction</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/advanced/status-handlers.html#writing-status-handlers" class="sidebar-link">Writing status handlers</a></li><li class="sidebar-sub-header"><a href="/goyave/guide/advanced/status-handlers.html#registering-status-handlers" class="sidebar-link">Registering status handlers</a></li></ul></li><li><a href="/goyave/guide/advanced/logging.html" class="sidebar-link">Logging</a></li></ul></section></li></ul> </aside> <main class="page"> <div class="theme-default-content content__default"><h1 id="status-handlers"><a href="#status-handlers" class="header-anchor">#</a> Status Handlers <span class="badge tip" style="vertical-align:top;" data-v-15b7b770>Since v2.4.0</span></h1> <p></p><div class="table-of-contents"><ul><li><a href="#introduction">Introduction</a></li><li><a href="#writing-status-handlers">Writing status handlers</a></li><li><a href="#registering-status-handlers">Registering status handlers</a></li></ul></div><p></p> <h2 id="introduction"><a href="#introduction" class="header-anchor">#</a> Introduction</h2> <p>Status handlers are regular handlers executed during the <strong>finalization</strong> step of the <a href="/goyave/guide/architecture-concepts.html#requests">request's lifecycle</a> if the response body is empty but a status code has been set. Status handler are mainly used to implement a custom behavior for user or server errors (400 and 500 status codes).</p> <p>Goyave comes with a default error status handler. When a panic occurs or the <a href="/goyave/guide/basics/responses.html#response-error"><code>Response.Error()</code></a> method is called, the request's status is set to <code>500 Internal Server Error</code> and the request error is set. The latter can be accessed using <a href="/goyave/guide/basics/responses.html#response-geterror"><code>Response.GetError()</code></a>. The error is printed in the console. If debugging is enabled in the config, the error is also written in the response using the JSON format, and the stacktrace is printed in the console. If debugging is not enabled, the following is returned:</p> <div class="language-json extra-class"><pre class="language-json"><code><span class="token punctuation">{</span>
    42      <span class="token property">&quot;error&quot;</span><span class="token operator">:</span> <span class="token string">&quot;Internal Server Error&quot;</span>
    43  <span class="token punctuation">}</span>
    44  </code></pre></div><p>The status handler covering all the other errors in the <code>400</code> and <code>500</code> status codes ranges has a similar behavior but doesn't print anything to the console. For example, if the user requests a route that doesn't exist, the following is returned:</p> <div class="language-json extra-class"><pre class="language-json"><code><span class="token punctuation">{</span>
    45      <span class="token property">&quot;error&quot;</span><span class="token operator">:</span> <span class="token string">&quot;Not Found&quot;</span>
    46  <span class="token punctuation">}</span>
    47  </code></pre></div><h2 id="writing-status-handlers"><a href="#writing-status-handlers" class="header-anchor">#</a> Writing status handlers</h2> <p>As said earlier, status handlers are regular handlers. The only difference is that they are executed at the very end of the request's lifecycle. Ideally, create a new controller for your status handlers.</p> <p><code>http/controller/status/status.go</code>:</p> <div class="language-go extra-class"><pre class="language-go"><code><span class="token keyword">package</span> status
    48  
    49  <span class="token keyword">import</span> <span class="token string">&quot;github.com/System-Glitch/goyave/v2&quot;</span>
    50  
    51  <span class="token keyword">func</span> <span class="token function">NotFound</span><span class="token punctuation">(</span>response <span class="token operator">*</span>goyave<span class="token punctuation">.</span>Response<span class="token punctuation">,</span> request <span class="token operator">*</span>goyave<span class="token punctuation">.</span>Request<span class="token punctuation">)</span> <span class="token punctuation">{</span>
    52      <span class="token keyword">if</span> err <span class="token operator">:=</span> response<span class="token punctuation">.</span><span class="token function">RenderHTML</span><span class="token punctuation">(</span>response<span class="token punctuation">.</span><span class="token function">GetStatus</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> <span class="token string">&quot;errors/404.html&quot;</span><span class="token punctuation">,</span> <span class="token boolean">nil</span><span class="token punctuation">)</span><span class="token punctuation">;</span> err <span class="token operator">!=</span> <span class="token boolean">nil</span> <span class="token punctuation">{</span>
    53          response<span class="token punctuation">.</span><span class="token function">Error</span><span class="token punctuation">(</span>err<span class="token punctuation">)</span>
    54      <span class="token punctuation">}</span>
    55  <span class="token punctuation">}</span>
    56  </code></pre></div><h2 id="registering-status-handlers"><a href="#registering-status-handlers" class="header-anchor">#</a> Registering status handlers</h2> <p>Status handlers are registered in the <strong>router</strong>.</p> <h4 id="router-statushandler"><a href="#router-statushandler" class="header-anchor">#</a> Router.StatusHandler</h4> <p>Set a handler for responses with an empty body. The handler will be automatically executed if the request's life-cycle reaches its end and nothing has been written in the response body.</p> <p>Multiple status codes can be given. The handler will be executed if one of them matches.</p> <p>Status handlers are <strong>inherited</strong> as a copy in sub-routers. Modifying a child's status handler will not modify its parent's. That means that you can define different status handlers for certain route groupes if you so desire.</p> <table><thead><tr><th>Parameters</th> <th>Return</th></tr></thead> <tbody><tr><td><code>handler Handler</code></td> <td><code>void</code></td></tr> <tr><td><code>status int</code></td> <td></td></tr> <tr><td><code>additionalStatuses ...int</code></td> <td></td></tr></tbody></table> <p><strong>Example:</strong></p> <div class="language-go extra-class"><pre class="language-go"><code><span class="token keyword">func</span> <span class="token function">errorStatusHandler</span><span class="token punctuation">(</span>response <span class="token operator">*</span>Response<span class="token punctuation">,</span> request <span class="token operator">*</span>Request<span class="token punctuation">)</span> <span class="token punctuation">{</span>
    57  	message <span class="token operator">:=</span> <span class="token keyword">map</span><span class="token punctuation">[</span><span class="token builtin">string</span><span class="token punctuation">]</span><span class="token builtin">string</span><span class="token punctuation">{</span>
    58  		<span class="token string">&quot;error&quot;</span><span class="token punctuation">:</span> http<span class="token punctuation">.</span><span class="token function">StatusText</span><span class="token punctuation">(</span>response<span class="token punctuation">.</span><span class="token function">GetStatus</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
    59  	<span class="token punctuation">}</span>
    60  	response<span class="token punctuation">.</span><span class="token function">JSON</span><span class="token punctuation">(</span>response<span class="token punctuation">.</span><span class="token function">GetStatus</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span> message<span class="token punctuation">)</span>
    61  <span class="token punctuation">}</span>
    62  
    63  <span class="token comment">// Use &quot;errorStatusHandler&quot; for empty responses having status 404 or 405.</span>
    64  router<span class="token punctuation">.</span><span class="token function">StatusHandler</span><span class="token punctuation">(</span>errorStatusHandler<span class="token punctuation">,</span> <span class="token number">404</span><span class="token punctuation">,</span> <span class="token number">405</span><span class="token punctuation">)</span>
    65  </code></pre></div></div> <footer class="page-edit"><div class="edit-link"><a href="https://github.com/System-Glitch/goyave/edit/master/docs_src/src/guide/advanced/status-handlers.md" target="_blank" rel="noopener noreferrer">Edit this page on GitHub</a> <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg></div> <!----></footer> <div class="page-nav"><p class="inner"><span class="prev">
    66        ←
    67        <a href="/goyave/guide/advanced/cors.html" class="prev">
    68          CORS
    69        </a></span> <span class="next"><a href="/goyave/guide/advanced/logging.html">
    70          Logging
    71        </a>
    72        →
    73      </span></p></div> </main></div><div class="global-ui"><!----></div></div>
    74      <script src="/goyave/assets/js/app.092490a7.js" defer></script><script src="/goyave/assets/js/4.75a9cc68.js" defer></script><script src="/goyave/assets/js/1.121dd9ed.js" defer></script><script src="/goyave/assets/js/14.b933d8cf.js" defer></script><script src="/goyave/assets/js/5.c83f1192.js" defer></script>
    75    </body>
    76  </html>