Trả lời nhanh: File quy ước cho dự án di động khác dự án web ở ba chỗ, và đó cũng là ba phần đáng viết nhất: quy ước quản lý trạng thái vì mỗi dự án một kiểu và agent hay trộn lẫn; cấm thêm gói mới khi chưa hỏi vì mỗi gói thêm vào làm nặng ứng dụng và có thể kéo theo quyền truy cập mới; và ràng buộc về chuỗi hiển thị cùng quyền vì hai thứ này ảnh hưởng trực tiếp tới việc bị cửa hàng từ chối. Giữ file dưới một trăm dòng.
Nguyên tắc viết file quy ước đã nói ở bài giới thiệu chung. Bài này nói phần riêng của dự án di động, những điều mà một file quy ước cho dự án web không có và nếu thiếu thì bạn sẽ phải nhắc lại mỗi ngày.
Ba phần riêng của dự án di động
Quản lý trạng thái. Đây là chỗ mỗi dự án một kiểu, và mô hình được huấn luyện trên mọi kiểu nên nó chọn ngẫu nhiên nếu bạn không nói. Kết quả là hai kiểu trong cùng một ứng dụng, thứ tích tụ thành nợ kỹ thuật nhanh nhất.
Quản lý gói phụ thuộc. Với web, thêm một thư viện chỉ làm gói tải về nặng thêm. Với di động, nó làm ứng dụng nặng thêm và có thể kéo theo một quyền truy cập mới, thứ khiến bạn phải khai báo lại với cửa hàng và có nguy cơ bị từ chối.
Chuỗi hiển thị và quyền. Chuỗi viết thẳng trong màn hình thì không dịch được, và quyền khai thừa thì bị cửa hàng hỏi. Cả hai đều là những thứ sửa sau rất tốn công.
Một file mẫu đủ dùng
# Quy ước dự án ứng dụng bán hàng ## Cấu trúc- lib/screens/ màn hình, chỉ hiển thị, không gọi mạng- lib/services/ gọi API và xử lý dữ liệu- lib/models/ kiểu dữ liệu dùng chung- lib/core/ phần lõi, không sửa khi chưa hỏi ## Quy ước code- Quản lý trạng thái theo đúng cách trong lib/screens/orders- Mọi chuỗi hiển thị lấy từ file dịch, không viết thẳng trong widget- Widget dài quá 150 dòng thì tách thành widget con- Không gọi mạng trực tiếp trong widget ## Không được làm- Không thêm gói mới khi chưa hỏi- Không sửa file cấu hình đóng gói của Android và iOS- Không thêm quyền truy cập mới vào file khai báo- Không sửa file trong lib/corePhần cấm ngắn hơn phần quy ước nhưng quan trọng hơn. Ba dòng cấm cuối liên quan trực tiếp tới việc phát hành: sửa nhầm một trong ba chỗ đó có thể làm bản dựng thất bại hoặc bị cửa hàng từ chối.
Vì sao cấm thêm gói lại quan trọng
Agent rất hay thêm một gói mới vì đó là đường nhanh nhất tới kết quả. Với dự án di động, mỗi gói thêm vào kéo theo bốn hệ quả:
- Ứng dụng nặng thêm, và người dùng ở vùng mạng yếu cảm nhận điều đó khi tải.
- Có thể thêm quyền truy cập, buộc bạn cập nhật khai báo an toàn dữ liệu với cửa hàng.
- Thêm một phụ thuộc phải bảo trì, và gói bỏ hoang sẽ chặn bạn khi cần nâng phiên bản nền tảng.
- Có thể xung đột với gói đang dùng, gây lỗi lúc đóng gói chứ không phải lúc viết code.
Vì vậy dòng cấm này nên đi kèm một câu hướng dẫn: nếu cần một chức năng chưa có, hãy nêu ra và đề xuất hai phương án, một dùng thư viện sẵn có và một dùng gói mới, rồi để bạn chọn.
Ràng buộc liên quan tới phát hành
Ba thứ nên ghi vì chúng ảnh hưởng tới việc lên cửa hàng:
Không tự sửa file khai báo quyền. Mọi thay đổi ở đó phải do bạn duyệt, vì nó kéo theo phần khai báo an toàn dữ liệu, theo bài chuẩn bị trước khi nộp.
Không tự đổi mã phiên bản. Số này do luồng phát hành quản, và agent đổi tay sẽ làm hỏng trình tự.
Không đụng file cấu hình ký. Đây là nơi trỏ tới khóa ký, và một thay đổi nhầm ở đó làm bản phát hành không dựng được, xem bài về keystore.
Ba dòng này ngắn nhưng chúng chặn đúng những sự cố xảy ra vào ngày bạn cần phát hành gấp.
Giữ file ngắn
Nguyên tắc chung vẫn đúng: file này được nạp ở mọi lượt nên mỗi dòng thừa đều tốn tiền và làm loãng phần quan trọng. Dưới một trăm dòng là mức lành mạnh.
Phần dài hơn nên tách:
- Quy trình dài, ví dụ cách dựng một màn hình theo mẫu công ty, đóng thành skill theo bài viết skill đầu tiên.
- Quyết định thiết kế ghi vào tài liệu trong repo và trỏ tới khi cần.
- Danh sách màn hình mẫu chỉ cần một dòng trỏ tới thư mục, không cần liệt kê hết.
Cách phân tầng đầy đủ nằm ở bài về memory, và nguyên tắc chung của file quy ước ở bài CLAUDE.md.
Luật nào đáng viết, luật nào chỉ làm loãng
| Loại luật | Đáng viết không | Lý do |
|---|---|---|
| Cấm thêm thư viện mới nếu chưa hỏi | Rất đáng | Mỗi thư viện thêm vào ứng dụng di động là thêm dung lượng và thêm rủi ro khi phát hành |
| Phiên bản tối thiểu của hệ điều hành được hỗ trợ | Rất đáng | Quyết định trực tiếp mã nào dùng được, mã nào không |
| Quy ước đặt tên biến | Ít đáng | Công cụ định dạng tự động làm tốt hơn và không tốn chỗ trong tệp luật |
| Cách trình bày câu trả lời | Không nên đặt ở đây | Đó là sở thích cá nhân, nên đặt ở cấu hình riêng của từng người |
| Danh sách tệp và thư mục không được sửa | Rất đáng | Nhất là tệp cấu hình phát hành và tệp chứa khóa ký |
Ràng buộc riêng của dự án di động
- Ràng buộc về dung lượng gói. Nêu rõ ngưỡng hiện tại và yêu cầu báo trước khi vượt. Người dùng ở nơi mạng yếu bỏ cài đặt vì lý do này nhiều hơn bạn nghĩ.
- Quy tắc về quyền truy cập. Xin thêm một quyền là một lần phải giải trình khi gửi duyệt ứng dụng. Ghi rõ quyền nào đã có và cấm tự thêm.
- Khác biệt giữa hai nền tảng. Nêu nền nào là nền chính, và mọi thay đổi phải chạy thử trên cả hai trước khi coi là xong.
Giữ tệp luật ngắn
# Nguyen tac: tep luat cang dai thi cang it duoc doc ky # Muc tieu: duoi mot man hinh cuon# Moi dong phai tra loi duoc cau hoi: bo dong nay di thi hong gi # Neu mot muc can giai thich dai, hay de o tai lieu rieng# va trong tep luat chi ghi mot dong tro toi tai lieu do # Xem lai tep luat moi quy:# - bo luat da het hieu luc vi du an doi# - bo luat chua bao gio bi vi pham, no khong con la rang buoc that # Dat tep luat trong kho ma va coi no nhu ma nguon:# moi thay doi deu di qua yeu cau gop ma de ca doi cung bietCâu hỏi thường gặp
File quy ước cho dự án di động khác web ở đâu?
Ba chỗ: phải nói rõ cách quản lý trạng thái vì mỗi dự án một kiểu, phải cấm thêm gói bừa vì gói mới có thể kéo theo quyền truy cập, và phải ràng buộc chuỗi hiển thị cùng các file liên quan tới phát hành.
Vì sao không nên để agent tự thêm thư viện?
Vì với ứng dụng di động, mỗi gói làm ứng dụng nặng thêm, có thể thêm quyền truy cập buộc bạn khai báo lại với cửa hàng, và trở thành một phụ thuộc phải bảo trì lâu dài.
Nên viết file này dài bao nhiêu?
Dưới một trăm dòng. Nó được nạp ở mọi lượt gọi nên dài ra là vừa tốn tiền vừa làm luật quan trọng bị chìm. Quy trình dài thì tách sang skill, quyết định thiết kế thì ghi vào tài liệu.
Dự án dùng cả Android và iOS thì viết chung một file được không?
Được, và nên chung vì phần lớn quy ước áp dụng cho cả hai. Chỉ tách riêng khi có ràng buộc chỉ đúng với một nền tảng, ví dụ quy tắc về file cấu hình đóng gói của từng bên.