You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: content/controllers.md
+35-11Lines changed: 35 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -58,18 +58,18 @@ This method will return a 200 status code and the associated response, which in
58
58
<tr>
59
59
<td>Library-specific</td>
60
60
<td>
61
-
We can use the library-specific (e.g., Express) <a href="http://expressjs.com/en/api.html#res" rel="nofollow" target="_blank">response object</a>, which can be injected using the <code>@Res()</code> decorator in the method handler signature (e.g., <code>findAll(@Res() response)</code>). With this approach, you have the ability (and the responsibility), to use the native response handling methods exposed by that object. For example, with Express, you can construct responses using code like <code>response.status(200).send()</code>
61
+
We can use the library-specific (e.g., Express) <a href="https://expressjs.com/en/api.html#res" rel="nofollow" target="_blank">response object</a>, which can be injected using the <code>@Res()</code> decorator in the method handler signature (e.g., <code>findAll(@Res() response)</code>). With this approach, you have the ability to use the native response handling methods exposed by that object. For example, with Express, you can construct responses using code like <code>response.status(200).send()</code>.
62
62
</td>
63
63
</tr>
64
64
</table>
65
65
66
-
> warning **Warning**You cannot use both approaches at the same time. Nest detects when the handler is using either `@Res()` or `@Next()`, indicating you have chosen the library-specific option. If both approaches are used at the same time, the Standard approach is **automatically disabled** for this single route and will no longer work as expected.
66
+
> warning **Warning** Nest detects when the handler is using either `@Res()` or `@Next()`, indicating you have chosen the library-specific option. If both approaches are used at the same time, the Standard approach is **automatically disabled** for this single route and will no longer work as expected. To use both approaches at the same time (for example, by injecting the response object to only set cookies/headers but still leave the rest to the framework), you must set the `passthrough` option to `true` in the `@Res({{ '{' }} passthrough: true {{ '}' }})` decorator.
67
67
68
68
<app-banner-enterprise></app-banner-enterprise>
69
69
70
70
#### Request object
71
71
72
-
Handlers often need access to the client **request** details. Nest provides access to the [request object](http://expressjs.com/en/api.html#req) of the underlying platform (Express by default). We can access the request object by instructing Nest to inject it by adding the `@Req()` decorator to the handler's signature.
72
+
Handlers often need access to the client **request** details. Nest provides access to the [request object](https://expressjs.com/en/api.html#req) of the underlying platform (Express by default). We can access the request object by instructing Nest to inject it by adding the `@Req()` decorator to the handler's signature.
73
73
74
74
```typescript
75
75
@@filename(cats.controller)
@@ -98,12 +98,12 @@ export class CatsController {
98
98
99
99
> info **Hint** In order to take advantage of `express` typings (as in the `request: Request` parameter example above), install `@types/express` package.
100
100
101
-
The request object represents the HTTP request and has properties for the request query string, parameters, HTTP headers, and body (read more [here](http://expressjs.com/en/api.html#req)). In most cases, it's not necessary to grab these properties manually. We can use dedicated decorators instead, such as `@Body()` or `@Query()`, which are available out of the box. Below is a list of the provided decorators and the plain platform-specific objects they represent.
101
+
The request object represents the HTTP request and has properties for the request query string, parameters, HTTP headers, and body (read more [here](https://expressjs.com/en/api.html#req)). In most cases, it's not necessary to grab these properties manually. We can use dedicated decorators instead, such as `@Body()` or `@Query()`, which are available out of the box. Below is a list of the provided decorators and the plain platform-specific objects they represent.
@@ -137,6 +137,10 @@ The request object represents the HTTP request and has properties for the reques
137
137
<td><code>@Ip()</code></td>
138
138
<td><code>req.ip</code></td>
139
139
</tr>
140
+
<tr>
141
+
<td><code>@HostParam()</code></td>
142
+
<td><code>req.hosts</code></td>
143
+
</tr>
140
144
</tbody>
141
145
</table>
142
146
@@ -181,7 +185,7 @@ export class CatsController {
181
185
}
182
186
```
183
187
184
-
It's that simple. Nest provides the rest of the standard HTTP request endpoint decorators in the same fashion - `@Put()`, `@Delete()`, `@Patch()`, `@Options()`, `@Head()`, and `@All()`. Each represents its respective HTTP request method.
188
+
It's that simple. Nest provides decorators for all of the standard HTTP methods: `@Get()`, `@Post()`, `@Put()`, `@Delete()`, `@Patch()`, `@Options()`, and `@Head()`. In addition, `@All()` defines an endpoint that handles all of them.
185
189
186
190
#### Route wildcards
187
191
@@ -285,7 +289,7 @@ findOne(params) {
285
289
```typescript
286
290
@@filename()
287
291
@Get(':id')
288
-
findOne(@Param('id') id): string {
292
+
findOne(@Param('id') id: string): string {
289
293
return`This action returns a #${id} cat`;
290
294
}
291
295
@@switch
@@ -479,6 +483,8 @@ export class CatsController {
479
483
}
480
484
```
481
485
486
+
>info**Hint**NestCLIprovidesagenerator (schematic) thatautomaticallygenerates**alltheboilerplatecode**tohelpusavoiddoingallofthis, and make the developer experience much simpler. Read more about this feature [here](/recipes/crud-generator).
487
+
482
488
#### Getting up and running
483
489
484
490
With the above controller fully defined, Nest still doesn't know that `CatsController` exists and as a result won't create an instance of this class.
@@ -500,9 +506,9 @@ We attached the metadata to the module class using the `@Module()` decorator, an
500
506
501
507
<app-banner-shop></app-banner-shop>
502
508
503
-
#### Appendix: Library-specificapproach
509
+
#### Library-specificapproach
504
510
505
-
Sofarwe'vediscussedtheNeststandardwayofmanipulatingresponses. Thesecondwayofmanipulatingtheresponseistousealibrary-specific [responseobject](http://expressjs.com/en/api.html#res). In order to inject a particular response object, we need to use the `@Res()` decorator. To show the differences, let's rewrite the `CatsController` to the following:
511
+
Sofarwe'vediscussedtheNeststandardwayofmanipulatingresponses. Thesecondwayofmanipulatingtheresponseistousealibrary-specific [responseobject](https://expressjs.com/en/api.html#res). In order to inject a particular response object, we need to use the `@Res()` decorator. To show the differences, let's rewrite the `CatsController` to the following:
506
512
507
513
```typescript
508
514
@@filename()
@@ -540,6 +546,24 @@ export class CatsController {
540
546
}
541
547
```
542
548
543
-
Though this approach works, and does in fact allow for more flexibility in some ways by providing full control of the response object (headers manipulation, library-specific features, and so on), it should be used with care. In general, the approach is much less clear and does have some disadvantages. The main disadvantages are that you lose compatibility with Nest features that depend on Nest standard response handling, such as Interceptors and the `@HttpCode()` decorator. Also, your code can become platform-dependent (as underlying libraries may have different APIs on the response object), and harder to test (you'll have to mock the response object, etc.).
549
+
Though this approach works, and does in fact allow for more flexibility in some ways by providing full control of the response object (headers manipulation, library-specific features, and so on), it should be used with care. In general, the approach is much less clear and does have some disadvantages. The main disadvantage is that your code become platform-dependent (as underlying libraries may have different APIs on the response object), and harder to test (you'll have to mock the response object, etc.).
550
+
551
+
Also, in the example above, you lose compatibility with Nest features that depend on Nest standard response handling, such as Interceptors and `@HttpCode()` / `@Header()` decorators. To fix this, you can set the `passthrough` option to `true`, as follows:
As a result, the Nest standard approach should always be preferred when possible.
569
+
Now you can interact with the native response object (for example, set cookies or headers depending on certain conditions), but leave the rest to the framework.
> info **Hint** Note that `validateCustomDecorators` option must be set to true. `ValidationPipe` does not validate arguments annotated with the custom decorators by default.
179
+
171
180
#### Decorator composition
172
181
173
182
Nest provides a helper method to compose multiple decorators. For example, suppose you want to combine all decorators related to authentication into a single decorator. This could be done with the following construction:
During your development with NestJS, you may encounter various errors as you learn the framework.
4
+
5
+
#### "Cannot resolve dependency" error
6
+
7
+
Probably the most common error message is about Nest not being able to resolve dependencies of a provider. The error message usually looks something like this:
8
+
9
+
```bash
10
+
Nest can't resolve dependencies of the <provider> (?). Please make sure that the argument <unknown_token> at index [<index>] is available in the <module> context.
11
+
12
+
Potential solutions:
13
+
- If <unknown_token> is a provider, is it part of the current <module>?
14
+
- If <unknown_token> is exported from a separate @Module, is that module imported within <module>?
15
+
@Module({
16
+
imports: [ /* the Module containing <unknown_token> */ ]
17
+
})
18
+
```
19
+
20
+
21
+
The most common culprit of the error, is not having the `provider` in the module's `providers` array. Please make sure that the provider is indeed in the `providers` array and following [standard NestJS provider practices](/fundamentals/custom-providers#di-fundamentals).
22
+
23
+
There are a few gotchas, that are common. One is putting a provider in an `imports` array. If this is the case, the error will have the provider's name where `<module>` should be.
24
+
25
+
If you run across this error while developing, take a look at the module mentioned in the error message and look at its `providers`. For each provider in the `providers` array, make sure the module has access to all of the dependencies. Often times, `providers` are duplicated in a "Feature Module" and a "Root Module" which means Nest will try to instantiate the provider twice. More than likely, the module containing the `provider` being duplicated should be added in the "Root Module"'s `imports` array instead.
26
+
27
+
#### "Circular dependency" error
28
+
29
+
Occasionally you'll find it difficult to avoid [circular dependencies](/fundamentals/circular-dependency) in your application. You'll need to take some steps to help Nest resolve these. Errors that arise from circular dependencies look like this:
30
+
31
+
```bash
32
+
Nest cannot create the <module> instance.
33
+
The module at index [<index>] of the <module>"imports" array is undefined.
34
+
35
+
Potential causes:
36
+
- A circular dependency between modules. Use forwardRef() to avoid it. Read more: https://docs.nestjs.com/fundamentals/circular-dependency
37
+
- The module at index [<index>] is of type"undefined". Check your import statements and the type of the module.
38
+
39
+
Scope [<module_import_chain>]
40
+
# example chain AppModule -> FooModule
41
+
```
42
+
43
+
Circular dependencies can arise from both providers depending on each other, or typescript files depending on each other forconstants, such as exporting constants from a module file and importing themin a service file. In the latter case, it is advised to create a separate file for your constants. In the former case, please follow the guide on ciruclar dependencies and make sure that both the modules **and** the providers are marked with `forwardRef`.
0 commit comments