Ba công cụ, ba câu hỏi khác nhau. Android Lint hỏi: code có gọi API không tồn tại trên minSdk, thiếu quyền, thừa resource hay sai manifest không. ktlint hỏi: file này có đúng định dạng chung của team không. detekt hỏi: hàm này có quá phức tạp, class này có quá nhiều trách nhiệm không. Dùng một công cụ cho cả ba câu hỏi thì bạn hoặc bỏ sót lỗi thật, hoặc tạo ra hàng nghìn cảnh báo không ai đọc. Dưới đây là cách phân vai chúng, kèm cấu hình Gradle và bước CI chạy được.
Mục lục
Cập nhật 2026
- AGP 9.5 vẫn tích hợp Android Lint, cấu hình bằng block
lint { }ở module; đây là công cụ duy nhất hiểu API level, manifest, resource và check Compose của Google. - Kotlin 2.4.21 stable, K2 là compiler mặc định; ktlint và detekt chạy trên PSI nên không cần bật chế độ riêng, nhưng detekt 1.23.x nhúng compiler Kotlin 2.0.21, nên cú pháp 2.4 mới có thể không parse — thử trên CI trước.
- ktlint stable ở dòng 1.x, detekt ở dòng 1.23.x; bản 2.0 của cả hai vẫn alpha. Bài này không pin version: bạn pin trong version catalog và nâng có kiểm soát.
- compose-rules phát hành ruleset cho cả detekt và ktlint, nên rule đặc thù Compose không phải tự viết.
Ba tầng kiểm tra: đừng để công cụ chồng việc lên nhau
Mỗi công cụ trả lời một loại câu hỏi, và câu trả lời của chúng không thay thế nhau:
- Ngữ nghĩa (Android Lint): code này chạy đúng trên thiết bị thật với minSdk và targetSdk đã khai báo không? Lint biết
NotificationChannelcần API 26, biết bạn thiếuPOST_NOTIFICATIONS, biết drawable không dùng, biếtcontentDescriptionbị bỏ trống. - Định dạng (ktlint): thụt lề, xuống dòng, import, dấu phẩy cuối dòng có theo một bộ quy tắc thống nhất không? Việc cơ học, phải tự động hóa được.
- Cấu trúc (detekt): hàm 80 dòng, độ phức tạp 25, class 30 hàm,
GlobalScopetrong coroutine — không crash ngay nhưng làm codebase chậm lại.
Phần chồng lấn: detekt-formatting dùng chính rule của ktlint, còn Android Lint cũng có vài check style. Bật cả ba mà không phân vai thì một dòng code bị báo ba lần với ba định dạng report. Quy ước: định dạng thuộc ktlint, ngữ nghĩa thuộc Android Lint, cấu trúc thuộc detekt; tắt detekt-formatting nếu đã chạy ktlint.
Android Lint: tầng ngữ nghĩa, hiểu Android thật
Lint không tự chạy trong mọi build: gọi ./gradlew lintDebug hoặc lintRelease, và nên gọi trong CI thay vì trông chờ IDE. Mỗi phát hiện có một issue ID và một mức độ: fatal, error, warning, informational, ignore. Mức độ đặt trong lint.xml, còn bật/tắt và baseline đặt trong block Gradle:
// File: app/build.gradle.kts
android {
compileSdk = 36
lint {
baseline = file("lint-baseline.xml")
abortOnError = true
warningsAsErrors = true
checkDependencies = true
sarifReport = true
disable += setOf("GradleDependency", "NewerVersionAvailable")
}
}
abortOnError = true là mặc định. checkDependencies = true mở phân tích sang thư viện — hữu ích vì nhiều AndroidX library tự ship lint check, nhưng mang về cảnh báo từ code bạn không sửa được. GradleDependency và NewerVersionAvailable chỉ báo dependency mới, không phải lỗi code; việc đó thuộc về bot dependency, không phải CI lint.
warningsAsErrors = true chỉ nên bật sau khi dọn sạch warning hiện có, nếu không 400 cảnh báo biến codebase thành thứ không build được. Với dự án cũ, baseline là cách đi tiếp: lần chạy đầu ghi toàn bộ phát hiện vào lint-baseline.xml, các lần sau chỉ báo phát hiện mới; xóa file rồi chạy lại để tạo baseline mới.
ktlint: một định dạng, một nguồn sự thật
ktlint đọc .editorconfig ở root repo, nên cùng một file cấu hình có tác dụng cho CLI, Gradle và IDE có hỗ trợ EditorConfig. Từ ktlint 1.0, code style mặc định là ktlint_official; hai lựa chọn còn lại là intellij_idea và android_studio.
Vài key bạn phải quyết định dưới section [*.{kt,kts}]: ktlint_code_style = android_studio nếu Studio là nguồn định dạng chính; max_line_length (ktlint_official mặc định 140, android_studio mặc định 100); ktlint_function_naming_ignore_when_annotated_with = Composable để rule đặt tên không đòi viết hoa chữ đầu của Composable; và tắt từng rule bằng ktlint_standard_<rule-id> = disabled khi team có quy ước riêng.
// File: app/build.gradle.kts
plugins {
id("com.android.application")
alias(libs.plugins.kotlin.android)
alias(libs.plugins.ktlint)
}
ktlint {
filter {
exclude("**/generated/**")
exclude("**/build/**")
}
}
dependencies {
ktlintRuleset(libs.compose.rules.ktlint)
}
ktlintCheck gắn vào task check; ktlintFormat phải gọi tay. ktlint cũng có baseline (--baseline=ktlint-baseline.xml), nhưng với codebase cũ cách rẻ hơn là chạy ktlintFormat một lần, commit riêng phần định dạng, rồi chỉ nhận thay đổi mới. Baseline chỉ hợp khi có rule bạn không muốn sửa tự động.
detekt: code smell, complexity và rule riêng của bạn
detekt chia rule thành các ruleset: complexity, style, potential-bugs, coroutines, exceptions, naming, performance. Bật buildUponDefaultConfig = true rồi chỉ override những ngưỡng muốn siết, thay vì copy toàn bộ file mặc định vào repo.
# File: config/detekt/detekt.yml
complexity:
LongMethod:
threshold: 40
CyclomaticComplexMethod:
threshold: 12
TooManyFunctions:
thresholdInFiles: 15
style:
MagicNumber:
ignoreNumbers: ['-1', '0', '1', '2']
ReturnCount:
max: 3
coroutines:
GlobalCoroutineUsage:
active: true
evotek:
NoPrintln:
active: true
Plugin Gradle nhận file cấu hình, baseline và report:
// File: build.gradle.kts (root)
plugins {
alias(libs.plugins.detekt)
}
detekt {
buildUponDefaultConfig = true
config.setFrom(files("config/detekt/detekt.yml"))
baseline = file("config/detekt/detekt-baseline.xml")
parallel = true
ignoreFailures = false
reports {
sarif.required.set(true)
}
}
dependencies {
detektPlugins(libs.compose.rules.detekt)
}
./gradlew detekt chạy kiểm tra; detektBaseline ghi toàn bộ phát hiện hiện tại vào baseline; detektGenerateConfig sinh file cấu hình mặc định. Rule riêng của team viết bằng Kotlin:
// File: detekt-rules/src/main/kotlin/NoPrintln.kt
package com.evotek.detekt
import io.gitlab.arturbosch.detekt.api.*
import org.jetbrains.kotlin.psi.KtCallExpression
class NoPrintln(config: Config) : Rule(config) {
override val issue = Issue(
id = "NoPrintln",
severity = Severity.Style,
description = "Dùng logger thay vì println trong mã production",
debt = Debt.FIVE_MINS,
)
override fun visitCallExpression(expression: KtCallExpression) {
super.visitCallExpression(expression)
if (expression.calleeExpression?.text == "println") {
report(CodeSmell(issue, Entity.from(expression), "println bị cấm ở main source set"))
}
}
}
class EvotekRuleSetProvider : RuleSetProvider {
override val ruleSetId = "evotek"
override fun instance(config: Config) =
RuleSet(ruleSetId, listOf(NoPrintln(config)))
}
Rule set phải khai báo trong META-INF/services/io.gitlab.arturbosch.detekt.api.RuleSetProvider để detekt tìm thấy; section evotek trong config ở trên bật nó lên. Rule tự viết nên có test bằng detekt-test; một rule sai làm team tắt detekt nhanh hơn rule mặc định.
So sánh: công cụ nào bắt gì, trả giá bằng gì
| Công cụ | Bắt được gì | Chi phí |
|---|---|---|
| Android Lint | API level, manifest, quyền, resource, accessibility, Compose misuse, thư viện lỗi thời | Chậm hơn ktlint; baseline dễ ẩn nợ; gắn chặt với AGP |
| ktlint | Định dạng, thụt lề, import, khoảng trắng, quy tắc đặt tên cơ bản | Rất ít hiểu biết ngữ nghĩa; autofix có thể đổi code; tranh cãi style |
| detekt | Complexity, code smell, coroutine, exception, rule kiến trúc do bạn viết | Cần cấu hình và baseline; type resolution chậm; dễ bật quá nhiều rule |
Ba công cụ không cạnh tranh. Android Lint không format code, ktlint không biết hàm có 12 nhánh if, detekt không biết READ_MEDIA_IMAGES đã bị hạn chế trên Android 13+. Bỏ công cụ nào cũng để lại một khoảng trống cụ thể.
Đưa vào CI, pre-commit và IDE
CI là nơi quyết định: máy local có thể bỏ qua, pipeline thì không. Một job chạy cả ba, thu report một lần và fail sau khi đã chạy hết task:
# File: .github/workflows/static-analysis.yml
name: static-analysis
on: [pull_request]
jobs:
lint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-java@v4
with:
distribution: temurin
java-version: '17'
- uses: gradle/actions/setup-gradle@v4
- run: ./gradlew lintDebug ktlintCheck detekt --continue
- uses: actions/upload-artifact@v4
if: always()
with:
name: static-analysis-reports
path: |
**/build/reports/lint-results-debug.sarif
**/build/reports/detekt/*.sarif
AGP 9.5 cần JDK 17 và Gradle 9.6+. Cờ --continue cho Gradle chạy nốt task còn lại dù một task fail, nên PR không phải sửa từng lỗi qua nhiều vòng CI; exit code vẫn khác 0 và merge vẫn bị chặn. Report SARIF tải lên làm artifact để review đúng file, đúng dòng, thay vì đọc log 2.000 dòng.
Pre-commit hook nên giữ nhẹ: gọi ./gradlew ktlintCheck trên module bị sửa, hoặc dùng ktlint CLI chỉ trên file staged. Đừng đưa detekt đầy đủ vào mỗi commit — thời gian Gradle khởi động cộng phân tích sẽ khiến team dùng --no-verify.
Trong IDE, Android Lint có sẵn và hiển thị ngay trong editor; plugin ktlint và detekt (phần lớn là bản cộng đồng) đưa phát hiện vào gutter. Rủi ro lớn nhất là formatter: nếu IDE format theo style khác ktlint, mỗi lần lưu file tạo diff không liên quan. Chọn một code style, cấu hình IDE theo đúng style đó, tắt “reformat on save” nếu nó không đọc EditorConfig.
Baseline cho codebase cũ: nợ có sổ, không phải thùng rác
Baseline không làm code sạch hơn. Nó chỉ đổi câu hỏi từ “làm sao sửa hết 1.500 cảnh báo” thành “làm sao không thêm cảnh báo thứ 1.501”. Cách triển khai có thứ tự:
- Chốt định dạng trước. Chạy
ktlintFormattoàn repo, commit một PR chỉ chứa định dạng, thêm commit đó vào.git-blame-ignore-revs; trộn với thay đổi logic thì review vô nghĩa. - Sinh baseline. Chạy lint một lần để tạo
lint-baseline.xml, chạydetektBaselineđể tạodetekt-baseline.xml, commit cả hai; CI chỉ đỏ khi có phát hiện mới. - Giữ baseline trong review. PR thêm entry baseline là PR che vấn đề; review diff file baseline như review code, cấm sửa tay.
- Siết theo quý. Xóa và sinh lại sau khi sửa một phần nợ; số entry không giảm trong hai quý nghĩa là baseline đã thành thùng rác. Sửa file nào thì sửa luôn phát hiện của file đó.
Với lint, baseline so khớp theo issue và vị trí, nên refactor có thể làm entry cũ hết khớp và sinh cảnh báo “mới” không thực sự mới; xác nhận rồi sinh lại baseline trong PR riêng. Với detekt, baseline là XML do task sinh, đừng viết tay.
Compose: lint riêng cho Composable
Android Lint có bộ check Compose đi kèm thư viện Compose: ComposableNaming, ComposeUnrememberedState, ComposeModifierMissing — quên remember, đặt tên sai quy ước, thiếu tham số Modifier. Chúng chạy cùng lintDebug, không cần cài thêm.
Phần sâu hơn do compose-rules xử lý: Modifier dùng lại, Modifier không có default, thứ tự Modifier, component emit nhiều content, dùng collection không ổn định, hoặc còn dùng Material 2. Project phát hành hai artifact cho detekt và ktlint; chọn đúng một theo công cụ bạn đã có, và chọn bản compose-rules khớp dòng detekt (bản mới nhất có thể đã nhắm detekt 2.0 alpha). Với ktlint, dependency nằm ở ktlintRuleset; với detekt, nó nằm ở detektPlugins.
Khi check Compose báo sai, suppress hẹp: @SuppressLint("ComposeModifierMissing") cho Android Lint, @Suppress("...") cho detekt/ktlint, kèm lý do. Suppress cả file là cách nhanh nhất để rule biến mất khỏi dự án.
Bẫy thường gặp
- Bật tất cả rule ngay ngày đầu.
allRules = truetrên codebase 5 năm tuổi sinh hàng nghìn phát hiện; team tắt detekt trong tuần đầu. Bắt đầu bằng default config, siết từng nhóm rule sau mỗi quý. - Để baseline sống mãi. Baseline không có ngày hết hạn sẽ che cả vấn đề đã sửa lẫn vấn đề mới trong file cũ. Sinh lại theo lịch, theo dõi số entry như một metric nợ kỹ thuật.
- Chiến tranh formatter giữa IDE và ktlint. ktlint_official mặc định 140 ký tự, android_studio mặc định 100; IDE reformat theo profile riêng sẽ đảo qua đảo lại mỗi lần lưu. Chọn một code style, đặt
max_line_lengthmột lần, và để ktlint là nguồn sự thật. - Chạy detekt trên code generated. Room, KSP, Hilt sinh code trong
build/generated; phân tích chúng tạo cảnh báo về code bạn không được sửa và làm chậm build. Giới hạn detekt ởsrc, loại trừ**/generated/**ở cả ktlint. - Biến warning thành error mà chưa triage.
warningsAsErrors = truekhi còn warning cũ làm build đỏ vì lý do không liên quan đến PR. Phân loại trước: lỗi ngữ nghĩa là error, cảnh báo style là warning, dependency mới là việc của bot. - Bật detekt-formatting song song ktlint. Hai công cụ báo cùng một lỗi với hai format report; chọn ktlint cho định dạng và tắt ruleset formatting của detekt.
Checklist
- Chốt
.editorconfigvới mộtktlint_code_style,max_line_lengthvà quy ước Composable naming. - Bật
lint { baseline, abortOnError, checkDependencies, sarifReport }; tách check dependency ra khỏi check code. - Commit
lint-baseline.xmlvàdetekt-baseline.xml; cấm sửa tay, chỉ sinh lại. - CI chạy
lintDebug ktlintCheck detekt --continuetrên JDK 17, lưu SARIF làm artifact. - Pre-commit chỉ chạy ktlint trên file staged; detekt để CI và pre-push.
- Thêm compose-rules cho đúng một công cụ, không cài cả hai artifact.
Nhìn tới 2027
Kotlin 2.5.0 dự kiến ra tháng 12/2026; ktlint 2.0 và detekt 2.0 vẫn alpha, đừng đưa bản alpha vào pipeline production. Khi lên 2.x bạn sẽ đổi artifact, plugin và phải đọc migration guide, nên pin version trong catalog và nâng ở PR riêng. Android Lint vẫn là nơi Google đặt check Compose và API mới.
Nếu chưa dựng Gradle theo cấu trúc chuẩn, đọc lại Gradle là gì và cách dùng trong phát triển Android. Lint và detekt không thay thế test: chúng bắt vấn đề tĩnh, còn hành vi đúng sai do kiểm thử đơn vị với JUnit đảm bảo. Toàn bộ lộ trình nằm ở Android Developer Roadmap.



