Նոր Scala նախագծերի ստեղծման հուսալի checklist
Հիմնական կարգավորումներ և պրակտիկաներ, որոնք արժե դիտարկել, երբ ուզում եք բարելավել ձեր build-երը կամ մշակման աշխատանքային ընթացքը։ Դրանցից մի քանիսը լավ են աշխատում որպես template-ների մաս։
Նոր Scala նախագիծ սկսելը սովորաբար ավարտվում է build կոնֆիգուրացիաներն այլ տեղից պատճենելով։ Արդեն որոշ ժամանակ գոյություն ունեցող build կոնֆիգուրացիան հակված է կուտակել բազմաթիվ օգտակար կարգավորումներ և plugin-ներ։ Որոշ կազմակերպություններ լռելյայն կարգավորումները տեղափոխում են ներքին plugin-ների մեջ կամ օգտվում են GitHub template-ների նման հնարավորություններից։ Այդպիսի template-ները հազվադեպ են իմաստ ունենում այն համատեքստից դուրս, որի համար ստեղծվել են, ուստի ամեն նպատակի համար մեկ վերջնական նախագծային կմախք կառուցելը արժանի չէ։
Փոխարենը ես կցանկանայի առաջարկել checklist՝ հիմնական կարգավորումների և պրակտիկաների ցանկ, որոնք արժե դիտարկել, երբ ուզում եք բարելավել ձեր build-երը կամ մշակման աշխատանքային ընթացքը։ Դրանցից մի քանիսը լավ են աշխատում որպես template-ների մաս։ Մյուսները պարզապես անհրաժեշտ քայլեր են, որոնք ես ուզում եմ իրականացված տեսնել, մինչ որևէ մեկը կսկսի ներդրում անել։
Checklist-ի ակնարկ (TLDR)
Եթե նախընտրում եք ամբողջ checklist-ը թերթել առանց ձանձրալի պարբերություններ կարդալու, ահա այն՝
- .gitignore
- sbt-dotenv և direnv
- local.conf
- .sbtopts
- Java-ի տարբերակ
- Կոմպիլյատորի flag-եր
- .scalafmt.conf
- .scala-steward.conf կամ renovate
- publish-ի կարգավորումներ
- .mergify.conf կամ automerge
- GitHub actions և CODEOWNERS
- Հիմնական գրադարաններ
- SNAPSHOT-ների TTL-ներ
- Բոնուս. nix
.gitignore
Նախապես պատրաստեք մանրակրկիտ .gitignore ֆայլ, որպեսզի նյարդայնացնող, ավելորդ տեղային ֆայլերը չհայտնվեն pull request-ներում։
sbt-dotenv և direnv
Նախագծի հատուկ կոնֆիգուրացիոն արժեքները հաճախ տրվում են միջավայրի փոփոխականներով։ Օրինակ՝ Scala նախագծերում ընդունված է դրանց հղվել application.conf-ում, ապա տեղային, թեստային և արտադրական միջավայրերի համար սահմանել իրական արժեքները։ direnv-ը լայնորեն կիրառվող գործիք է, որը ավտոմատ կերպով բեռնում է միջավայրը ձեր ընթացիկ shell-ում, հենց որ մտնում եք .envrc ֆայլ պարունակող նախագծի պանակ, օրինակ այսպիսի բովանդակությամբ՝
export KAFKA_HOST=localhost
export KAFKA_PORT=9131
Նման ֆայլը sbt console-ին կապելը շատ հարմար է, հատկապես երբ այն գործարկում եք IDE-ից։ Դրա համար արժե ուշադրություն դարձնել sbt-dotenv plugin-ին։ Իմաստ ունի այն կարգավորել որպես global plugin, որպեսզի կիրառվի ձեր բոլոր տեղային նախագծերում։
Սկսեք ~/.sbt/1.0/plugins/dotenv.sbt ֆայլը ստեղծելով՝
addSbtPlugin("nl.gn0s1s" % "sbt-dotenv" % "3.0.0")
Ես նաև խորհուրդ եմ տալիս plugin-ի լռելյայն ֆայլի անունը .env-ից փոխել .envrc-ի։ Դա direnv-ի օգտագործած ստանդարտ անունն է. ավելի հայտնի գործիք է, որը ծառայում է նաև այլ նպատակների։ Դրա համար ավելացրեք .sbt/1.0/envrc.sbt՝
ThisBuild / envFileName := ".envrc"
Դրանից հետո ամեն անգամ sbt console գործարկելիս այն միջավայրի փոփոխականները կբեռնի աշխատանքային տարածքի արմատում գտնվող .envrc ֆայլից։ Ֆայլը պետք է մնա տեղային, ուստի համոզվեք, որ git-ը այն անտեսում է. տես .gitignore բաժինը։
(Նշում. sbt-dotenv-ը հիմնվում է reflection-ի վրա։ Java 17-ից սկսած reflection-ն արգելված է, ուստի sbt-dotenv-ը գործարկման ժամանակ խափանվում է։ Հաջորդ բաժինը՝ .sbtopts-ի մասին, բացատրում է, թե ինչպես շտկել սա)։
local.conf
Միջավայրի փոփոխականներից բացի՝ մեկ այլ օգտակար պրակտիկա է application.conf-ի գրառումների վերասահմանումը։ Ավելացրեք local.conf-ը .gitignore-ում, որպեսզի մշակողները կարողանան ստեղծել src/main/resources/local.conf ֆայլ, որը ներառում է application.conf-ը, օրինակ՝
include "application.conf"
akka {
loggers = ["akka.event.slf4j.Slf4jLogger"]
loglevel = "DEBUG"
stdout-loglevel = "DEBUG"
}
Ֆայլն ուժի մեջ է մտնում, երբ հավելվածը գործարկվում է -Dconfig.file=path/to/src/main/resources/local.conf պարամետրով։ Այս պարամետրը sbt-ին կարող եք փոխանցել մի քանի ձևով՝
- սովորական sbt console-ը գործարկելիս՝
sbt 'set javaOptions+="-Dconfig.file=path/to/src/main/resources/local.conf"; test:runMain com.myapp.MyMain' - IntelliJ-ի sbt console-ում՝ պարզապես ավելացրեք
-Dconfig.file=...«sbt settings»-ի «VM parameters»-ում - IntelliJ-ի «Run» կոնֆիգուրացիաներում՝ ինչպես sbt console-ում, օգտագործեք «VM parameters» դաշտը
- և նույն կերպ՝ այլ գործիքներում
.sbtopts
Սա հարմար տեղ է build-երի և sbt console-ի համար sbt կամ Java տարբերակներ սահմանելու համար։ Որպեսզի ընդհանուր հավաքածուն կիսեք բոլոր մշակողների և CI-ի հետ, դրեք դրանք .sbtopts-ում, օրինակ՝
Reflection-ի միացում Java-ի նոր տարբերակներում (անհրաժեշտ է sbt-dotenv-ի համար Java 17+-ում)՝
-J--add-opens=java.base/java.util=ALL-UNNAMED
-J--add-opens=java.base/java.lang=ALL-UNNAMED
Հիշողության հատուկ կարգավորումների սահմանում՝
-J-Xmx5G
-J-Xms1G
-J-Xss2M
Հատուկ sbt տարբերակների սահմանում (ամբողջական ցանկը այստեղ է)՝
-Dsbt.task.timings=true
Java-ի տարբերակ
Ժամանակ առ ժամանակ երկար հետաքննությունն ավարտվում է այն հայտնագործությամբ, որ ձեր տեղային Java-ի տարբերակը տարբերվում է CI-ի օգտագործածից, իսկ հավելվածի հետ տեղակայվող տարբերակը կարող է բոլորովին այլ լինել։ Ձեր նախագծի բոլոր շերտերում Java-ի տարբերակի համաձայնեցումը հնարավոր է, բայց ոչ պարզ։
Տեղային մեքենայում մշակողները հաճախ օգտվում են sdkman-ից կամ jenv-ից։ Առաջինը ունիվերսալ է և կարող է համադրվել .envrc-ի հետ, բայց միակ մոտեցումը, որ կարողացա գտնել, հեռու է գեղեցիկ լինելուց։ Հակառակ դեպքում օգտագործեք կա՛մ .sdkmanrc, կա՛մ .java-version, այս գործիքների համար նախատեսված ֆայլերը։
Ձեր Continuous Integration pipeline-ը, մյուս կողմից, ամենայն հավանականությամբ ունի իր JDK կոնֆիգուրացիան (տես այս GitHub Action-ը, որը կարդում է այն ֆայլից), և հետո կա sbt-native-packager-ը, որը build.sbt-ում պահանջում է base image-ի սահմանում։
Ես երբեք չէի տեսել, որ JDK-ի այս բոլոր տարբերակները հավաքված լինեն մեկ տեղում, մինչև չհանդիպեցի nix-ին, որը մանրամասն կնկարագրեմ առանձին բլոգային գրառման մեջ։
Կոմպիլյատորի flag-եր
Հարց. կարո՞ղ եք նկատել խնդիրն այս կոդում։
def doStuff(data: Data): F[Unit] = {
Logger[F].info(s"Logging important metadata: ${data.metadata}")
processor.process(data).void
}
Պատասխան. ակնհայտորեն կոդում բացակայում է >>-ը, որը կապում է logger-ի վերադարձրած F[Unit]-ը processor-ի կանչից վերադարձվող մյուս F[Unit]-ի հետ, որն էլ մեր վերջնական արդյունքն է։ Բայց արդյոք իրո՞ք այդքան ակնհայտ է։ Ամենայն հավանականությամբ՝ այո, երբ ձեզ ասում են երկու տողանոց կոդում սխալ փնտրել, բայց ավելի մեծ համատեքստում դա հեշտ է բաց թողնել։
Խնդիրն այն է, որ Scala 2.13 կոմպիլյատորը լիովին լուռ է մնում, և այսպիսի սխալները կարող են անցնել code review-ներից։ Կոմպիլյատորի լռելյայն կարգավորումները գրեթե միշտ պետք է խստացնել, օրինակ՝ չօգտագործված և դեն նետված արժեքների ու այլ հնարավոր խնդիրների մասին զգուշացնելու համար։ sbt-tpolecat plugin-ը տրամադրում է sbt-ի կոմպիլյատորի flag-երի հիանալի հավաքածու։ Համադրեք այն ընտրովի զգուշացումների ճնշման հետ, և ամեն ինչ պատրաստ է։ Օրինակ՝ դրեք՝
scalacOptions += "-Wconf:src=src_managed/.*:s"
ձեր build կոնֆիգուրացիայի մեջ՝ ձայնազրկելու այն դասերի զգուշացումները, որոնք ScalaPB-ն գեներացնում է protobuf ֆայլերից։
.scalafmt.conf
Ձևաչափման կանոնների ներդրումը նախագծի կյանքի ուշ փուլում հանգեցնում է ցավոտ թարմացումների, ուստի սկզբում լավ կանոնների հավաքածու համաձայնեցնելը կարևոր է։ Ստորև ներկայացված են մի քանի կանոններ, որոնք ինձ դուր են գալիս, բայց հիշեք, որ կոդի ոճի կանոնները խիստ սուբյեկտիվ են՝
maxColumn = 140
// breaks long class/def definitions into multiline
verticalMultiline.atDefnSite = true
// forces newline before and after implicit params
newlines.implicitParamListModifierForce = [before, after]
// only format files tracked by git
project.git = true
// PreferCurlyFors: Replaces parentheses into curly braces in for comprehensions that contain multiple enumerator generators
// RedundantBraces, RedundantParens: Remove redundant braces, parens
rewrite.rules = [PreferCurlyFors, RedundantBraces, RedundantParens, SortImports]
// Add spaces next to curly braces in imports
spaces.inImportCurlyBraces = true
// more than standard align rules https://scalameta.org/scalafmt/docs/configuration.html#alignpresetmore
style = defaultWithAlign
// all infix operators can be exempted from applying continuation indentation
indentOperator.exemptScope = all
rewriteTokens {
"⇒" = "=>"
"→" = "->"
"←" = "<-"
}
.scala-steward.conf կամ renovate
Կախվածությունները թարմ պահելը բարդ գործընթաց է, որը պահանջում է կանոնավոր աշխատանք և հաճախ հետևում է հատուկ կանոնների։ Այսօր այն կարելի է ավտոմատացնել այնպիսի գործիքներով, ինչպիսիք են Scala Steward-ը կամ renovate-ը՝ լրացված dependabot-ով։ Երբեմն կարող եք ցանկանալ բաց թողնել որոշ գրադարաններ, սահմանել PR-ների վերնագրերը կամ սահմանափակել թարմացումների քանակը կամ հաճախականությունը։ Ճշգրտեք ձեր Scala Steward-ի կանոնները (տես այս հղումը և կազմեք հստակ սահմանված կոնֆիգ։
publish-ի կարգավորումներ
Բազմամոդուլ sbt նախագծերում հաճախ բավական առանձնահատուկ է այն ընտրությունը, թե որ մոդուլները ինչպես պետք է մշակվեն՝
- Հրապարակվում են որպես artifact-ներ
- Հրապարակվում են որպես docker image-ներ
- Հրապարակվում են scaladoc-ով
- Չեն հրապարակվում
Իմ սկզբնական build.sbt-ը գրեթե միշտ օգտվում է հետևյալից՝
-
Resolver-ների լռելյայն ցանկ
-
Ուղի դեպի տեղային ivy credentials
-
Հրապարակման կոնֆիգուրացիա
-
Docker-ի հիմնական կարգավորումներ, ինչպիսիք են base image-ը կամ փաթեթի անունը
-
Compile / packageDoc / publishArtifact := falsecommonSettings-ում յուրաքանչյուր մոդուլի համար, ինչը բաց է թողնում scaladoc-ը և զգալիորեն կրճատում build-ի ժամանակը։
Հավաքածու՝lazy val noPublishSettings = Seq( publish := {}, publishLocal := {} ) lazy val dockerNoPublishSettings = Seq( Docker / publishLocal := {}, Docker / publish := {} )
որը հետո կարելի է կիրառել այսպես՝
.settings(noPublishSettings)
.settings(dockerNoPublishSettings)
այն մոդուլներին, որոնք չպետք է հրապարակվեն։
Կարգավորեք հրապարակումը նախապես, որպեսզի ձեր template-ի վրա հիմնված ապագա repository-ներին հնարավորինս քիչ լրացուցիչ աշխատանք պետք լինի։
.mergify.conf կամ automerge
Շատ իրավիճակներ կան, երբ PR-ների ավտոմատ merge-ն օգտակար է։ Օրինակ՝
- կախվածությունների թարմացման bot-ի բացած հաստատված PR-ների ավտոմատ merge
- որոշակի ֆայլեր փոփոխող PR-ների ավտոմատ merge
Դիտեք .mergify.conf-ի օրինակ՝ մեր կիրառած որոշ կանոններով։ Հիշեք, որ mergify-ը անվճար է միայն բաց կոդի համար, ուստի GitHub automerge-ը կամ renovate-ը կարող են ավելի հարմար լինել ձեր նախագծին։ Կոնֆիգուրացիայի օրինակ՝
# Enables automatic merge of master -> PR for Scala Steward PRs
# created by user 'github-actions', when all checks
# pass (including review approvals)
name: automerge
on:
pull_request:
types:
- labeled
- unlabeled
- synchronize
- edited
- ready_for_review
- reopened
- unlocked
pull_request_review:
types:
- submitted
check_suite:
types:
- completed
jobs:
automerge:
runs-on: ubuntu-latest
if: github.event.pull_request.user.login == 'github-actions'
steps:
- name: automerge
uses: "pascalgn/automerge-action@v0.15.3"
env:
GITHUB_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
MERGE_FILTER_AUTHOR: "github-actions"
MERGE_METHOD: "squash"
MERGE_LABELS: ""
MERGE_RETRIES: "15"
MERGE_RETRY_SLEEP: "20000"
UPDATE_LABELS: ""
GitHub actions և CODEOWNERS
Վերևում բերեցի GitHub action-ի մեկ օրինակ, որը լավ տեղավորվում է նախագծի template-ի մեջ՝ automerge։ Ձեր կարծիքով ի՞նչ այլ action-ներ են կարևոր ունենալ, մինչ ներդրողները կսկսեն commit անել։
Ներդրողների մասին խոսելով՝ ես սիրում եմ ավելացնել .github/CODEOWNERS ֆայլ, որը թույլ է տալիս pull request-ների վերանայողներին նշանակել ավտոմատ կերպով նրա բովանդակության հիման վրա։ Պարտադիր չէ թվարկել անհատների, ֆայլը ընդունում է նաև թիմեր, օրինակ՝
@my-organization/alpha-team
Հիմնական գրադարաններ
Գրադարանները չեն պատկանում նախագծի template-ներին, բայց արժանի են տեղ գրավելու նոր կոդային բազա սկսելու checklist-ում։ Նրանցից շատերը համարվում են հիմնական օգտակար գործիքներ, որոնք հաճախ ուզում ենք ունենալ մեր նախագծում հենց սկզբից։ Օրինակ՝ Scala-ի մի ընկեր մշակող կազմել է հիանալի ցանկ՝ cats, refined, iron, chimney, ducktape, scala-newtype, monocle, quicklens, enumeratum, derevo, macwire, jam, PPrint, sbt-thank-you-stars։
Ձեր սկզբնական հավաքածուն կարող է պարունակել նաև գրադարաններ լոգավորման, մետրիկաների, թեստավորման և ձեր կազմակերպությունում ընդհանուր այլ խնդիրների համար։
Զգուշացում։ Ես չեմ առաջարկում նախագծերի միջև կիսվող «common libraries» plugin։ Ընդհակառակը՝ ես խուսափում եմ այդ մոտեցումից, քանի որ այն առաջացնում է սարսափելի կախվածությունների խնդիրներ և ստեղծում է ուռճացած մոդուլ՝ հարյուրավոր մեգաբայթ այնպիսի բաներով, որոնք գուցե պետք էլ չեն։ Առաջարկությունների checklist պահելը, որը թիմերը վերանայում են նոր կոդային բազա սկսելիս, շատ ավելի լավ է աշխատում։
SNAPSHOT-ների TTL-ներ
Որոշ իրավիճակներում SNAPSHOT կախվածությունների վրա մշակելն իմաստ ունի։ Պատկերացրեք երկու թիմ, որոնք վաղ նախատիպի փուլում հաճախ փոխանակում են «api» artifact-ը, մինչ համաձայնեցնում են հաղորդակցության պայմանագիրը։ Եթե դա ձեր դեպքն է, հիշեք, որ Coursier-ի TTL-ը 24 ժամ է, ուստի ձեր artifact-ները չեն թարմանա նույնիսկ նոր տարբերակի հրապարակումից հետո։ Այդ ժամկետը կրճատելու համար ընտրեք երկու տարբերակներից մեկը՝
-
Ավելացրեք TTL կոնֆիգուրացիան ձեր template-ում (
build.sbt)csrConfiguration := csrConfiguration.value.withTtl(Some(1.minute))
կամ
- Օգտագործեք վերը նշված
.envrcֆայլը, ավելացրեք exportCOURSIER_TTL=60s(կամ ձեզ անհրաժեշտ ցանկացած արժեք), ապա վերագործարկեք ձեր sbt սեսիան։
Նկատեք, որ նույնիսկ երբ sbt-ն ընդունում է այս կարգավորումները և ճիշտ վերաբեռնում է SNAPSHOT-ները, IntelliJ-ը, կարծես, դժվարանում է նկատել նոր artifact-ները։ Գուցե ամեն անգամ, երբ նոր SNAPSHOT է ներբեռնվում, այն պետք լինի վերագործարկել։
Բոնուս. nix
Ավելի վաղ կարճ նշեցի nix-ը որպես գործիք, որը կարող է ընդլայնել sbt-native-packager-ը՝ docker image-ներ կառուցելու համար ճիշտ այն jdk-ով, որն օգտագործվում է մշակման և CI-ի ժամանակ։ Nix-ը ավելին է առաջարկում, օրինակ՝ sdk-ների, գրադարանների և համակարգային փաթեթների ամբողջական միջավայրերի սահմանում, որոնք բեռնվում են միայն այն ժամանակ, երբ գտնվում եք ձեր նախագծի պանակում (nix shell-եր)։ «Nix all the things» զեկույցը nix-ի մեղմ ներածություն է սկսնակների համար։
Ամփոփում
Հուսով եմ՝ այս checklist-ը կօգնի ձեզ նախագծերի սկզբում կազմել հուսալի build կոնֆիգուրացիաներ։ Վստահ եմ՝ կան բազմաթիվ կետեր, որոնց մասին ես տեղյակ չեմ, ուստի եթե ունեք լրացումների կամ թարմացումների գաղափարներ, խնդրում եմ թողեք մեկնաբանություն։