Yêu cầu chuẩn hoá và validate các tham số truyền lên từ client là yêu cầu cơ bản khi xây dựng API Web. Mình đã có một bài hướng dẫn sử dụng Ecto.Changeset để chuẩn hoá trong bài viết này:
Parse và validate request param trong Phoenix với Ecto
Trong bài viết này, mình sẽ hướng dẫn một cách ngắn và đơn giản hơn bằng cách sử dụng thư viện sẵn có Tarams. Thư viện này thực ra là sử dụng lại Ecto.Changeset nhưng nó giúp cho chúng ta không phải lặp lại quá nhiều code như khi dùng Ecto.Changeset
Một vài tính năng thú vị của Tarams:
- Cung cấp cách thức đơn giản để định nghĩa các cấu trúc tham số
- Cho phép định nghĩa các giá trị default động
- Cho phép định nghĩa các hàm để cast giá trị về đúng kiểu dữ liệu
- Định nghĩa hàm để validate dữ liệu
Sau đây là cách sử dụng Tarams. Ví dụ chúng ta đang viết API để cập nhật profile của nhân viên. Yêu cầu là
1 2 3 4 5 6 7 | email: bắt buộc, đúng định dạng first_name: bắt buộc last_name: bắt buộc birthday: không bắt buộc, kiểu ngày tháng title: không bắt buộc start_date: ngày bắt đầu làm việc, ngày tháng, mặc định là ngày hiện tại |
1. Định nghĩa cấu trúc của tham số truyền lên khá đơn giản
1 2 3 4 5 6 7 8 9 | <span class="token attribute variable">@schema</span> <span class="token punctuation">%</span><span class="token punctuation">{</span> <span class="token attr-name">email:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:string</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token attr-name">first_name:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:string</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token attr-name">last_name:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:string</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token attr-name">title:</span> <span class="token atom symbol">:string</span><span class="token punctuation">,</span> <span class="token attr-name">birth_day:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:date</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token attr-name">start_date:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:date</span><span class="token punctuation">]</span> <span class="token punctuation">}</span> |
Schema đơn giản chỉ là một map với key là tên field và value là 1 list option của field đó.
2. Bây giờ thêm các ràng buộc
- Để đánh dấu 1 trường là bắt buộc, thêm option
required: true Taramcũng cho phép validate data sử dụng lại các hàm validate củaChangeset
1 2 3 4 5 6 7 8 9 | <span class="token attribute variable">@schema</span> <span class="token punctuation">%</span><span class="token punctuation">{</span> <span class="token attr-name">email:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:string</span><span class="token punctuation">,</span> <span class="token attr-name">required:</span> <span class="token boolean">true</span><span class="token punctuation">,</span> <span class="token attr-name">validate:</span> <span class="token punctuation">{</span><span class="token atom symbol">:format</span><span class="token punctuation">,</span> <span class="token regex">~r/@/</span><span class="token punctuation">}</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token attr-name">first_name:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:string</span><span class="token punctuation">,</span> <span class="token attr-name">required:</span> <span class="token boolean">true</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token attr-name">last_name:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:string</span><span class="token punctuation">,</span> <span class="token attr-name">required:</span> <span class="token boolean">true</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token attr-name">title:</span> <span class="token atom symbol">:string</span><span class="token punctuation">,</span> <span class="token attr-name">birth_day:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:date</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token attr-name">start_date:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:date</span><span class="token punctuation">]</span> <span class="token punctuation">}</span> |
3. Bây giờ thì set các giá trị default
default có thể là 1 giá trị hoặc 1 hàm. Mỗi khi parse tham số thì hàm này sẽ được gọi để lấy giá trị mặc định
1 2 3 4 5 6 7 | <span class="token attribute variable">@schema</span> <span class="token punctuation">%</span><span class="token punctuation">{</span> <span class="token operator">...</span> <span class="token attr-name">title:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:string</span><span class="token punctuation">,</span> <span class="token attr-name">default:</span> <span class="token string">"staff"</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token attr-name">birth_day:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:date</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token attr-name">start_date:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:date</span><span class="token punctuation">,</span> <span class="token attr-name">default:</span> <span class="token capture function">&Timex.today/0]</span> <span class="token punctuation">}</span> |
4. Cast các giá trị tham số về đúng kiểu
Nhiều các giá trị tham số truyền lên phải được chuyển về đúng các loại dữ liệu phức tạp như ngày tháng, list.
Ví dụ ngày tháng truyền lên là string 01/12/1994 thì phải chuyển về kiểu date để sử dụng lại được. Tarams hỗ trợ định nghĩa 1 hàm custom để cast giá trị, hàm này trả về
{:ok, value}nếu parse thành công{:error, error_message}nếu thất bại
1 2 3 4 5 6 7 8 9 10 11 | <span class="token keyword">def</span> parse_date<span class="token punctuation">(</span>date_str<span class="token punctuation">)</span> <span class="token keyword">do</span> Timex<span class="token punctuation">.</span>parse<span class="token punctuation">(</span>date_str<span class="token punctuation">,</span> <span class="token string">"{0D}/{0M}/{YYYY}"</span><span class="token punctuation">)</span> <span class="token keyword">end</span> <span class="token attribute variable">@schema</span> <span class="token punctuation">%</span><span class="token punctuation">{</span> <span class="token operator">...</span> <span class="token attr-name">title:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:string</span><span class="token punctuation">,</span> <span class="token attr-name">default:</span> <span class="token string">"staff"</span><span class="token punctuation">]</span><span class="token punctuation">,</span> <span class="token attr-name">birth_day:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:date</span><span class="token punctuation">,</span> <span class="token attr-name">cast_func:</span> <span class="token capture function">&parse_date/1],</span> <span class="token attr-name">start_date:</span> <span class="token punctuation">[</span><span class="token attr-name">type:</span> <span class="token atom symbol">:date</span><span class="token punctuation">,</span> <span class="token attr-name">default:</span> <span class="token capture function">&Timex.today/0]</span> <span class="token punctuation">}</span> |
5. Bây giờ sử dụng nào
1 2 3 4 5 6 7 8 9 | <span class="token keyword">def</span> update<span class="token punctuation">(</span>conn<span class="token punctuation">,</span> params<span class="token punctuation">)</span> <span class="token keyword">do</span> with <span class="token punctuation">{</span><span class="token atom symbol">:ok</span><span class="token punctuation">,</span> user_data<span class="token punctuation">}</span> <span class="token operator"><-</span> Tarams<span class="token punctuation">.</span>parse<span class="token punctuation">(</span><span class="token attribute variable">@schema</span><span class="token punctuation">,</span> params<span class="token punctuation">)</span> <span class="token keyword">do</span> <span class="token comment"># do anything with your params</span> <span class="token comment"># access data bằng atom key: user_data.email</span> <span class="token keyword">else</span> <span class="token punctuation">{</span><span class="token atom symbol">:error</span><span class="token punctuation">,</span> changset<span class="token punctuation">}</span> <span class="token operator">-></span> <span class="token comment"># return params error</span> <span class="token keyword">end</span> <span class="token keyword">end</span> |
Hàm parse sẽ parse và validate dữ liệu. Nếu mọi thứ đều ổn, sẽ trả về {:ok, data} và ngược lại thì trả về {:error, changeset}.
Done! Code của bạn sẽ trở nên đơn giản và ngắn gọn hơn nhiều