diff options
Diffstat (limited to 'search.xml')
| -rw-r--r-- | search.xml | 55 |
1 files changed, 55 insertions, 0 deletions
@@ -2741,6 +2741,61 @@ await prisma.$transaction(async tx => { </tags> </entry> <entry> + <title>NestJS 中 enableImplicitConversion 与 @Transform 的冲突</title> + <url>/2025/08/13/nestjs-enableImplicitConversion-and-transform/</url> + <content><![CDATA[<p>在 NestJS 生态中，<code>class-validator</code> 和 <code>class-transformer</code> 这两个库提供了以声明式的方式对 DTO 进行验证和转换。然而在处理布尔值时，如果在全局验证管道或仅仅是在局部同时开启了 <code>enableImplicitConversion</code>，可能会引入一个极其隐蔽且违反直觉的 Bug：前端传过来的布尔值恒为 true。</p> +<h2 id="一个简单的筛选功能"><a href="#一个简单的筛选功能" class="headerlink" title="一个简单的筛选功能"></a>一个简单的筛选功能</h2><p>假设正在开发一个电子商务平台的 API，需要实现一个产品列表的筛选功能。希望能够根据产品是否有库存 (<code>hasStock</code>)、是否为特色产品 (<code>isFeatured</code>) 等布尔条件进行筛选。</p> +<p>前端发出的请求 URL 可能如下所示： <code>/products?filter[hasStock]=true&filter[isFeatured]=false</code></p> +<p>在 NestJS 后端，首先会在 <code>main.ts</code> 中配置一个全局的 <code>ValidationPipe</code>，以自动处理 DTO 的验证和转换。为了方便，通常会启用 <code>enableImplicitConversion</code>，期望它能自动将 URL 查询参数中的字符串（如 <code>"123"</code>, <code>"true"</code>）转换为 DTO 中定义的类型（<code>number</code>, <code>boolean</code>）：</p> +<figure class="highlight typescript"><table><tr><td class="code"><pre><span class="line"><span class="comment">// main.ts</span></span><br><span class="line"><span class="keyword">import</span> { <span class="title class_">ValidationPipe</span> } <span class="keyword">from</span> <span class="string">'@nestjs/common'</span>;</span><br><span class="line"><span class="keyword">import</span> { <span class="title class_">NestFactory</span> } <span class="keyword">from</span> <span class="string">'@nestjs/core'</span>;</span><br><span class="line"><span class="keyword">import</span> { <span class="title class_">AppModule</span> } <span class="keyword">from</span> <span class="string">'./app.module'</span>;</span><br><span class="line"></span><br><span class="line"><span class="keyword">async</span> <span class="keyword">function</span> <span class="title function_">bootstrap</span>(<span class="params"></span>) {</span><br><span class="line"> <span class="keyword">const</span> app = <span class="keyword">await</span> <span class="title class_">NestFactory</span>.<span class="title function_">create</span>(<span class="title class_">AppModule</span>);</span><br><span class="line"></span><br><span class="line"> app.<span class="title function_">useGlobalPipes</span>(</span><br><span class="line"> <span class="keyword">new</span> <span class="title class_">ValidationPipe</span>({</span><br><span class="line"> <span class="attr">transform</span>: <span class="literal">true</span>, <span class="comment">// 启用转换</span></span><br><span class="line"> <span class="attr">whitelist</span>: <span class="literal">true</span>,</span><br><span class="line"> <span class="attr">forbidNonWhitelisted</span>: <span class="literal">true</span>,</span><br><span class="line"> <span class="attr">transformOptions</span>: {</span><br><span class="line"> <span class="comment">// 启用基于 TypeScript 类型的隐式转换</span></span><br><span class="line"> <span class="attr">enableImplicitConversion</span>: <span class="literal">true</span>, </span><br><span class="line"> },</span><br><span class="line"> }),</span><br><span class="line"> );</span><br><span class="line"> </span><br><span class="line"> <span class="comment">// ... 其他配置</span></span><br><span class="line"> <span class="keyword">await</span> app.<span class="title function_">listen</span>(<span class="number">3000</span>);</span><br><span class="line">}</span><br><span class="line"><span class="title function_">bootstrap</span>();</span><br></pre></td></tr></table></figure> + +<p>接着，定义一个 <code>ProductFilterDto</code> 来接收这些筛选条件。</p> +<p><strong>一个看似正确的 DTO 定义:</strong></p> +<figure class="highlight typescript"><table><tr><td class="code"><pre><span class="line"><span class="comment">// product-filter.dto.ts</span></span><br><span class="line"><span class="keyword">import</span> { <span class="title class_">IsBoolean</span>, <span class="title class_">IsOptional</span> } <span class="keyword">from</span> <span class="string">'class-validator'</span>;</span><br><span class="line"></span><br><span class="line"><span class="keyword">export</span> <span class="keyword">class</span> <span class="title class_">ProductFilterDto</span> {</span><br><span class="line"> <span class="meta">@IsOptional</span>()</span><br><span class="line"> <span class="meta">@IsBoolean</span>()</span><br><span class="line"> <span class="attr">hasStock</span>?: <span class="built_in">boolean</span>;</span><br><span class="line"></span><br><span class="line"> <span class="meta">@IsOptional</span>()</span><br><span class="line"> <span class="meta">@IsBoolean</span>()</span><br><span class="line"> <span class="attr">isFeatured</span>?: <span class="built_in">boolean</span>;</span><br><span class="line">}</span><br></pre></td></tr></table></figure> + +<p>在控制器中使用这个 DTO：</p> +<figure class="highlight typescript"><table><tr><td class="code"><pre><span class="line"><span class="comment">// products.controller.ts</span></span><br><span class="line"><span class="meta">@Controller</span>(<span class="string">'products'</span>)</span><br><span class="line"><span class="keyword">export</span> <span class="keyword">class</span> <span class="title class_">ProductsController</span> {</span><br><span class="line"> <span class="meta">@Get</span>()</span><br><span class="line"> <span class="title function_">find</span>(<span class="params"><span class="meta">@Query</span>(<span class="string">'filter'</span>) <span class="attr">filter</span>: <span class="title class_">ProductFilterDto</span></span>) {</span><br><span class="line"> <span class="comment">// 期望 filter.isFeatured 的值为 boolean false</span></span><br><span class="line"> <span class="variable language_">console</span>.<span class="title function_">log</span>(filter); </span><br><span class="line"> <span class="comment">// ... 业务逻辑</span></span><br><span class="line"> }</span><br><span class="line">}</span><br></pre></td></tr></table></figure> + +<p>当请求 <code>.../products?filter[isFeatured]=false</code> 到达时，本来期望在 <code>find</code> 方法中得到的 <code>filter.isFeatured</code> 的值是布尔类型的 <code>false</code>。然而，控制台输出的结果却令人意外：<code>{ isFeatured: true }</code></p> +<h2 id="问题剖析"><a href="#问题剖析" class="headerlink" title="问题剖析"></a>问题剖析</h2><p>这个问题的根源在于 <code>class-transformer</code> 内部的转换执行顺序，以及 JavaScript 中 <code>Boolean</code> 函数的类型转换行为。</p> +<p>所有通过 URL 查询参数传递的值，其本质都是字符串。当 NestJS 接收到请求时，<code>filter.isFeatured</code> 的原始值是字符串 <code>"false"</code>。</p> +<p><code>ValidationPipe</code> 启动 <code>class-transformer</code> 的转换流程。由于在全局管道中设置了 <code>enableImplicitConversion: true</code>，转换器会首先检查 DTO 属性的 TypeScript 类型。</p> +<ol> +<li><strong>隐式转换优先执行</strong>：<code>class-transformer</code> 看到 <code>ProductFilterDto</code> 中的 <code>isFeatured</code> 属性被声明为 <code>boolean</code> 类型。</li> +<li><strong>错误的类型转换</strong>：它立即尝试将字符串 <code>"false"</code> 转换为布尔值。这个转换等同于执行 <code>Boolean("false")</code>。在 JavaScript 中，任何非空字符串（包括 <code>"false"</code>）通过 <code>Boolean()</code> 构造函数转换后都会得到 <code>true</code>。</li> +<li><strong>结果覆盖</strong>：这个错误的 <code>true</code> 值被作为该属性的转换结果。</li> +</ol> +<p>此时，即使尝试添加一个自定义的 <code>@Transform</code> 装饰器来手动处理这个问题，也为时已晚。</p> +<p>例如，定义一个 <code>booleanTransformer</code>：</p> +<figure class="highlight typescript"><table><tr><td class="code"><pre><span class="line"><span class="comment">// boolean-transformer.ts</span></span><br><span class="line"><span class="keyword">export</span> <span class="keyword">const</span> <span class="title function_">booleanTransformer</span> = (<span class="params">{ value }: { value: <span class="built_in">any</span> }</span>) => {</span><br><span class="line"> <span class="keyword">if</span> (<span class="keyword">typeof</span> value === <span class="string">'string'</span>) {</span><br><span class="line"> <span class="keyword">return</span> value === <span class="string">'true'</span>;</span><br><span class="line"> }</span><br><span class="line"> <span class="keyword">return</span> value;</span><br><span class="line">};</span><br></pre></td></tr></table></figure> + +<p>然后更新 dto:</p> +<figure class="highlight typescript"><table><tr><td class="code"><pre><span class="line"><span class="comment">// product-filter.dto.ts (错误的尝试)</span></span><br><span class="line"><span class="keyword">import</span> { <span class="title class_">Transform</span> } <span class="keyword">from</span> <span class="string">'class-transformer'</span>;</span><br><span class="line"><span class="keyword">import</span> { <span class="title class_">IsBoolean</span>, <span class="title class_">IsOptional</span> } <span class="keyword">from</span> <span class="string">'class-validator'</span>;</span><br><span class="line"><span class="keyword">import</span> { booleanTransformer } <span class="keyword">from</span> <span class="string">'./boolean-transformer'</span>;</span><br><span class="line"></span><br><span class="line"><span class="keyword">export</span> <span class="keyword">class</span> <span class="title class_">ProductFilterDto</span> {</span><br><span class="line"> <span class="comment">// ...</span></span><br><span class="line"> <span class="meta">@IsOptional</span>()</span><br><span class="line"> <span class="meta">@Transform</span>(booleanTransformer) <span class="comment">// 添加自定义转换</span></span><br><span class="line"> <span class="meta">@IsBoolean</span>()</span><br><span class="line"> <span class="attr">isFeatured</span>?: <span class="built_in">boolean</span>;</span><br><span class="line">}</span><br></pre></td></tr></table></figure> + +<p>流程会变成这样：</p> +<ol> +<li>隐式转换首先执行：<code>Boolean("false")</code> -> <code>true</code>。</li> +<li><code>@Transform</code> 装饰器执行：此时传递给 <code>booleanTransformer</code> 的 <code>value</code> 已经是上一步错误转换后的布尔值 <code>true</code>，而不是原始的字符串 <code>"false"</code>。转换函数无从下手。</li> +</ol> +<p>最终结果依然是 <code>true</code>。</p> +<h2 id="解决方案：用-any-绕过隐式转换"><a href="#解决方案：用-any-绕过隐式转换" class="headerlink" title="## 解决方案：用 any 绕过隐式转换"></a>## 解决方案：用 <code>any</code> 绕过隐式转换</h2><p>要解决这个问题，核心在于阻止 <code>class-transformer</code> 进行那次错误的、优先的隐式转换，从而确保自定义 <code>@Transform</code> 函数能接收到最原始的字符串值。</p> +<p>最直接且侵入性最小的方法，是将 DTO 中相关属性的 TypeScript 类型从 <code>boolean</code> 改为 <code>any</code>。</p> +<p><strong>修正后的 DTO 定义:</strong></p> +<figure class="highlight typescript"><table><tr><td class="code"><pre><span class="line"><span class="comment">// product-filter.dto.ts (正确的实现)</span></span><br><span class="line"><span class="keyword">import</span> { <span class="title class_">Transform</span> } <span class="keyword">from</span> <span class="string">'class-transformer'</span>;</span><br><span class="line"><span class="keyword">import</span> { <span class="title class_">IsBoolean</span>, <span class="title class_">IsOptional</span> } <span class="keyword">from</span> <span class="string">'class-validator'</span>;</span><br><span class="line"><span class="keyword">import</span> { booleanTransformer } <span class="keyword">from</span> <span class="string">'./boolean-transformer'</span>;</span><br><span class="line"></span><br><span class="line"><span class="comment">// 一个更健壮的 booleanTransformer</span></span><br><span class="line"><span class="keyword">export</span> <span class="keyword">const</span> <span class="title function_">robustBooleanTransformer</span> = (<span class="params">{ value }: { value: <span class="built_in">string</span> }</span>) =></span><br><span class="line"> value === <span class="string">'true'</span> ? <span class="literal">true</span> : value === <span class="string">'false'</span> ? <span class="literal">false</span> : value;</span><br><span class="line"></span><br><span class="line"><span class="keyword">export</span> <span class="keyword">class</span> <span class="title class_">ProductFilterDto</span> {</span><br><span class="line"> <span class="meta">@IsOptional</span>()</span><br><span class="line"> <span class="meta">@Transform</span>(robustBooleanTransformer)</span><br><span class="line"> <span class="meta">@IsBoolean</span>()</span><br><span class="line"> <span class="attr">hasStock</span>?: <span class="built_in">any</span>; <span class="comment">// <-- 类型从 boolean 改为 any</span></span><br><span class="line"></span><br><span class="line"> <span class="meta">@IsOptional</span>()</span><br><span class="line"> <span class="meta">@Transform</span>(robustBooleanTransformer)</span><br><span class="line"> <span class="meta">@IsBoolean</span>()</span><br><span class="line"> <span class="attr">isFeatured</span>?: <span class="built_in">any</span>; <span class="comment">// <-- 类型从 boolean 改为 any</span></span><br><span class="line">}</span><br></pre></td></tr></table></figure> + +<p>这个改动虽然看起来放弃了 TypeScript 的类型检查，但在这个特定的场景下，它非常安全且有效。原因如下：</p> +<ol> +<li><strong>阻止隐式转换</strong>：当 <code>class-transformer</code> 看到属性类型是 <code>any</code> 时，它不知道该隐式转换成什么目标类型，因此会“跳过”这个属性的隐式转换步骤。</li> +<li><strong><code>@Transform</code> 接管</strong>：如此一来，原始的字符串值（<code>"true"</code> 或 <code>"false"</code>）就能原封不动地传递给 <code>robustBooleanTransformer</code> 函数。该函数现在可以正确地将字符串转换为期望的布尔值。</li> +<li><strong><code>@IsBoolean</code> 守门</strong>：在自定义转换完成后，<code>@IsBoolean()</code> 装饰器会进行最后的验证，确保存入 DTO 的最终值必须是 <code>true</code> 或 <code>false</code>。这保证了在业务逻辑中，该属性的类型是绝对安全的。</li> +</ol> +<p>好用，爱用。</p> +]]></content> + <tags> + <tag>Technique</tag> + </tags> + </entry> + <entry> <title>NestJS 嵌套查询参数解析错误分析与解决方案</title> <url>/2025/07/29/nestjs-nested-object-dto/</url> <content><![CDATA[<p>在开发 NestJS 应用程序时，一个常见的场景是根据复杂的条件筛选资源。当使用嵌套查询参数来表达这些条件时，例如通过 URL <code>http://localhost:3000/products/filter?filters[price][min]=100</code>，可能会意外地遇到 <code>property filters[price][min] should not exist</code> 错误。本文将深入剖析此问题背后的原因，并提供针对 Express 和 Fastify 两种底层框架的解决方案。</p> |