mirror of
https://github.com/metosin/reitit.git
synced 2025-12-18 00:41:12 +00:00
Exceptions docs
This commit is contained in:
Tommi Reiman
parent
c2d362dcd1
commit
83a0264698
4 changed files with 113 additions and 101 deletions
|
|
@ -48,3 +48,7 @@ Behind the scenes, both error formatters are backed by a multimethod, so they ar
|
|||
## More examples
|
||||
|
||||
See the [validating route data](route_data_validation.md) page.
|
||||
|
||||
## Runtime Exception
|
||||
|
||||
See [Exception Handling with Ring](../ring/exceptions.md).
|
||||
|
|
|
|||
|
|
@ -39,6 +39,7 @@
|
|||
["Data-driven Middleware" {:file "doc/ring/data_driven_middleware.md"}]
|
||||
["Transforming Middleware Chain" {:file "doc/ring/transforming_middleware_chain.md"}]
|
||||
["Middleware Registry" {:file "doc/ring/middleware_registry.md"}]
|
||||
["Exception Handling with Ring" {:file "doc/ring/exceptions.md"}]
|
||||
["Default Middleware" {:file "doc/ring/default_middleware.md"}]
|
||||
["Pluggable Coercion" {:file "doc/ring/coercion.md"}]
|
||||
["Route Data Validation" {:file "doc/ring/route_data_validation.md"}]
|
||||
|
|
|
|||
|
|
@ -21,107 +21,7 @@ Any Ring middleware can be used with `reitit-ring`, but using data-driven middle
|
|||
|
||||
## Exception Handling
|
||||
|
||||
A polished version of [compojure-api](https://github.com/metosin/compojure-api) exception handling. Catches all exceptions and invokes configured exception handler.
|
||||
|
||||
```clj
|
||||
(require '[reitit.ring.middleware.exception :as exception])
|
||||
```
|
||||
|
||||
### `exception/exception-middleware`
|
||||
|
||||
A preconfigured middleware using `exception/default-handlers`. Catches:
|
||||
|
||||
* Request & response [Coercion](coercion.md) exceptions
|
||||
* [Muuntaja](https://github.com/metosin/muuntaja) decode exceptions
|
||||
* Exceptions with `:type` of `:reitit.ring/response`, returning `:response` key from `ex-data`.
|
||||
* Safely all other exceptions
|
||||
|
||||
```clj
|
||||
(require '[reitit.ring :as ring])
|
||||
|
||||
(def app
|
||||
(ring/ring-handler
|
||||
(ring/router
|
||||
["/fail" (fn [_] (throw (Exception. "fail")))]
|
||||
{:data {:middleware [exception/exception-middleware]}})))
|
||||
|
||||
(app {:request-method :get, :uri "/fail"})
|
||||
;{:status 500
|
||||
; :body {:type "exception"
|
||||
; :class "java.lang.Exception"}}
|
||||
```
|
||||
|
||||
### `exception/create-exception-middleware`
|
||||
|
||||
Creates the exception-middleware with custom options. Takes a map of `identifier => exception request => response` that is used to select the exception handler for the thrown/raised exception identifier. Exception identifier is either a `Keyword` or a Exception Class.
|
||||
|
||||
The following handlers are available by default:
|
||||
|
||||
| key | description
|
||||
|--------------------------------------|-------------
|
||||
| `:reitit.ring/response` | value in ex-data key `:response` will be returned
|
||||
| `:muuntaja/decode` | handle Muuntaja decoding exceptions
|
||||
| `:reitit.coercion/request-coercion` | request coercion errors (http 400 response)
|
||||
| `:reitit.coercion/response-coercion` | response coercion errors (http 500 response)
|
||||
| `::exception/default` | a default exception handler if nothing else matched (default `exception/default-handler`).
|
||||
| `::exception/wrap` | a 3-arity handler to wrap the actual handler `handler exception request => response` (no default).
|
||||
|
||||
The handler is selected from the options map by exception identifier in the following lookup order:
|
||||
|
||||
1) `:type` of exception ex-data
|
||||
2) Class of exception
|
||||
3) `:type` ancestors of exception ex-data
|
||||
4) Super Classes of exception
|
||||
5) The ::default handler
|
||||
|
||||
```clj
|
||||
;; type hierarchy
|
||||
(derive ::error ::exception)
|
||||
(derive ::failure ::exception)
|
||||
(derive ::horror ::exception)
|
||||
|
||||
(defn handler [message exception request]
|
||||
{:status 500
|
||||
:body {:message message
|
||||
:exception (.getClass exception)
|
||||
:data (ex-data exception)
|
||||
:uri (:uri request)}})
|
||||
|
||||
(def exception-middleware
|
||||
(exception/create-exception-middleware
|
||||
(merge
|
||||
exception/default-handlers
|
||||
{;; ex-data with :type ::error
|
||||
::error (partial handler "error")
|
||||
|
||||
;; ex-data with ::exception or ::failure
|
||||
::exception (partial handler "exception")
|
||||
|
||||
;; SQLException and all it's child classes
|
||||
java.sql.SQLException (partial handler "sql-exception")
|
||||
|
||||
;; override the default handler
|
||||
::exception/default (partial handler "default")
|
||||
|
||||
;; print stack-traces for all exceptions
|
||||
::exception/wrap (fn [handler e request]
|
||||
(println "ERROR" (pr-str (:uri request)))
|
||||
(handler e request))})))
|
||||
|
||||
(def app
|
||||
(ring/ring-handler
|
||||
(ring/router
|
||||
["/fail" (fn [_] (throw (ex-info "fail" {:type ::failue})))]
|
||||
{:data {:middleware [exception-middleware]}})))
|
||||
|
||||
(app {:request-method :get, :uri "/fail"})
|
||||
; ERROR "/fail"
|
||||
; => {:status 500,
|
||||
; :body {:message "default"
|
||||
; :exception clojure.lang.ExceptionInfo
|
||||
; :data {:type :user/failue}
|
||||
; :uri "/fail"}}
|
||||
```
|
||||
See [Exception Handling with Ring](exceptions.md).
|
||||
|
||||
## Content Negotiation
|
||||
|
||||
|
|
|
|||
107
doc/ring/exceptions.md
Normal file
107
doc/ring/exceptions.md
Normal file
|
|
@ -0,0 +1,107 @@
|
|||
# Exception Handling with Ring
|
||||
|
||||
```clj
|
||||
[metosin/reitit-middleware "0.3.6"]
|
||||
```
|
||||
|
||||
Exceptions thrown in router creation can be [handled with custom exception handler](../basics/error_messages.md). By default, exceptions thrown at runtime from a handler or a middleware are not caught by the `reitit.ring/ring-handler`. A good practise is a have an top-level exception handler to log and format the errors for clients.
|
||||
|
||||
```clj
|
||||
(require '[reitit.ring.middleware.exception :as exception])
|
||||
```
|
||||
|
||||
### `exception/exception-middleware`
|
||||
|
||||
A preconfigured middleware using `exception/default-handlers`. Catches:
|
||||
|
||||
* Request & response [Coercion](coercion.md) exceptions
|
||||
* [Muuntaja](https://github.com/metosin/muuntaja) decode exceptions
|
||||
* Exceptions with `:type` of `:reitit.ring/response`, returning `:response` key from `ex-data`.
|
||||
* Safely all other exceptions
|
||||
|
||||
```clj
|
||||
(require '[reitit.ring :as ring])
|
||||
|
||||
(def app
|
||||
(ring/ring-handler
|
||||
(ring/router
|
||||
["/fail" (fn [_] (throw (Exception. "fail")))]
|
||||
{:data {:middleware [exception/exception-middleware]}})))
|
||||
|
||||
(app {:request-method :get, :uri "/fail"})
|
||||
;{:status 500
|
||||
; :body {:type "exception"
|
||||
; :class "java.lang.Exception"}}
|
||||
```
|
||||
|
||||
### `exception/create-exception-middleware`
|
||||
|
||||
Creates the exception-middleware with custom options. Takes a map of `identifier => exception request => response` that is used to select the exception handler for the thrown/raised exception identifier. Exception identifier is either a `Keyword` or a Exception Class.
|
||||
|
||||
The following handlers are available by default:
|
||||
|
||||
| key | description
|
||||
|--------------------------------------|-------------
|
||||
| `:reitit.ring/response` | value in ex-data key `:response` will be returned
|
||||
| `:muuntaja/decode` | handle Muuntaja decoding exceptions
|
||||
| `:reitit.coercion/request-coercion` | request coercion errors (http 400 response)
|
||||
| `:reitit.coercion/response-coercion` | response coercion errors (http 500 response)
|
||||
| `::exception/default` | a default exception handler if nothing else matched (default `exception/default-handler`).
|
||||
| `::exception/wrap` | a 3-arity handler to wrap the actual handler `handler exception request => response` (no default).
|
||||
|
||||
The handler is selected from the options map by exception identifier in the following lookup order:
|
||||
|
||||
1) `:type` of exception ex-data
|
||||
2) Class of exception
|
||||
3) `:type` ancestors of exception ex-data
|
||||
4) Super Classes of exception
|
||||
5) The ::default handler
|
||||
|
||||
```clj
|
||||
;; type hierarchy
|
||||
(derive ::error ::exception)
|
||||
(derive ::failure ::exception)
|
||||
(derive ::horror ::exception)
|
||||
|
||||
(defn handler [message exception request]
|
||||
{:status 500
|
||||
:body {:message message
|
||||
:exception (.getClass exception)
|
||||
:data (ex-data exception)
|
||||
:uri (:uri request)}})
|
||||
|
||||
(def exception-middleware
|
||||
(exception/create-exception-middleware
|
||||
(merge
|
||||
exception/default-handlers
|
||||
{;; ex-data with :type ::error
|
||||
::error (partial handler "error")
|
||||
|
||||
;; ex-data with ::exception or ::failure
|
||||
::exception (partial handler "exception")
|
||||
|
||||
;; SQLException and all it's child classes
|
||||
java.sql.SQLException (partial handler "sql-exception")
|
||||
|
||||
;; override the default handler
|
||||
::exception/default (partial handler "default")
|
||||
|
||||
;; print stack-traces for all exceptions
|
||||
::exception/wrap (fn [handler e request]
|
||||
(println "ERROR" (pr-str (:uri request)))
|
||||
(handler e request))})))
|
||||
|
||||
(def app
|
||||
(ring/ring-handler
|
||||
(ring/router
|
||||
["/fail" (fn [_] (throw (ex-info "fail" {:type ::failue})))]
|
||||
{:data {:middleware [exception-middleware]}})))
|
||||
|
||||
(app {:request-method :get, :uri "/fail"})
|
||||
; ERROR "/fail"
|
||||
; => {:status 500,
|
||||
; :body {:message "default"
|
||||
; :exception clojure.lang.ExceptionInfo
|
||||
; :data {:type :user/failue}
|
||||
; :uri "/fail"}}
|
||||
```
|
||||
Loading…
Reference in a new issue