Environment variables — нууцаа кодоос салгах

Танилцуулга

Өмнөх бүлгийн төгсгөлд бид нэг ноцтой дутагдлыг нэрлэсэн:

python

API_KEY = "нууц-түлхүүр-12345"

Түлхүүр кодонд шууд бичигдсэн. Механизм зөв ажиллаж байсан, гэхдээ хадгалалт нь буруу.

Энэ хичээлд бид түүнийг засна. Бид environment variable гэж юу болохыг сурч, .env файл ашиглан нууцаа кодоос гаргаж, тохиргоог цэгцтэй зохион байгуулна. Энэ бол зөвхөн энэ курсын дасгал биш — бүх мэргэжлийн программ ингэж бүтдэг.

Яагаад кодонд нууц байж болохгүй вэ

Дөрвөн тодорхой шалтгаан бий. Тус бүрийг ойлгох нь чухал, учир нь энэ бол зөвхөн зан заншил биш, бодит эрсдэл юм.

Нэгд, код хуваалцагддаг. Та кодоо GitHub-д байршуулбал, эсвэл хамт олонтойгоо хуваалцвал, эсвэл хэн нэгэнд харуулбал — түлхүүр тань хамт явна. GitHub дээр санамсаргүй нийтлэгдсэн нууц түлхүүрүүд бол бодит, өдөр бүр тохиолддог аюулгүй байдлын зөрчил юм. Робот программууд GitHub-ыг байнга скан хийж, ил гарсан түлхүүр хайдаг.

Хоёрт, код түүхтэй. Хэрэв та түлхүүрээ кодонд бичээд, дараа нь устгаад, git-д commit хийсэн бол — тэр түлхүүр түүхэнд үлдэнэ. Хэн ч хуучин хувилбарыг харж, түүнийг олж чадна. Устгах нь хангалтгүй.

Гуравт, орчин бүр өөр. Таны компьютер дээрх туршилтын түлхүүр болон бодит серверийн түлхүүр өөр байх ёстой. Кодонд бичсэн бол аль нэгийг нь сонгох ёстой болно — эсвэл кодоо орчин бүрд өөрчлөх ёстой.

Дөрөвт, солиход код өөрчлөгдөнө. Түлхүүр алдагдвал шинийг үүсгэх ёстой. Кодонд байвал кодоо засаж, дахин байршуулж, дахин ажиллуулах шаардлагатай. Тохиргоонд байвал — зөвхөн утгыг солино.

Эдгээрийг нэг зарчим болгон нэгтгэвэл: код ба тохиргоо тусдаа байх ёстой. Код нь юу хийхийг тодорхойлдог; тохиргоо нь хаана, ямар нөхцөлд ажиллахыг тодорхойлдог. Хоёулаа өөр хурдаар өөрчлөгддөг тул тусад нь байх ёстой.

Зүйрлэл: цоожны түлхүүр ба барилгын зураг

Барилгын зургийг (код) та хэн нэгэнд харуулж болно. Тэр зурагт хаана хаалга байгаа, ямар өрөө байгаа бичигдсэн. Хэн нэгэн зургийг харснаар барилгад орж чадахгүй.

Гэхдээ түлхүүрийг зурган дээр наавал — зураг харсан хүн бүр орж чадна. Түлхүүр зурганд байх ёсгүй; тэр таны халаасанд, тусдаа байх ёстой.

Environment variable бол тэр халаас юм. Код (зураг) нээлттэй байж болно; түлхүүр тусдаа, аюулгүй газар үлдэнэ.

Environment variable гэж юу вэ

Environment variable нь программын гаднаас, үйлдлийн системээс өгөгддөг тохируулга юм. Тэдгээр нь кодонд биш, программ ажиллаж байгаа орчинд амьдардаг.

Тэднийг ойлгох хамгийн энгийн арга: программ эхлэхэд систем түүнд нэр-утгын жагсаалт өгдөг. Программ тэр жагсаалтаас хэрэгтэй утгаа уншдаг.

Таны компьютер дээр аль хэдийн олон environment variable байгаа. Терминал дээр туршиж үзье ((venv) идэвхтэй байх шаардлагагүй):

python -c "import os; print(os.environ.get('PATH'))"

Урт зам гарч ирнэ — таны системийн PATH хувьсагч. Энэ бол Курс 1-2-т Python суулгахад тохируулж байсан тэр PATH юм. Environment variable нь шинэ зүйл биш; та зөвхөн одоо тэдгээрийг кодоос уншиж эхэлж байна.

os.environ — үндсэн арга

Python-д environment variable-ыг os модулиар уншина. Хоёр арга бий.

python

import os

# Арга 1: os.environ[...]
key = os.environ["API_KEY"]

# Арга 2: os.getenv(...)
key = os.getenv("API_KEY")

Ялгаа нь чухал. os.environ["API_KEY"] нь dictionary шиг ажилладаг — хувьсагч байхгүй бол KeyError шидэж, программ унана. os.getenv("API_KEY") нь байхгүй бол None буцаана, программ үргэлжилнэ.

os.getenv нь default утга ч авч чадна:

python

key = os.getenv("API_KEY", "default-утга")

Хувьсагч байхгүй бол "default-утга" буцаана.

Аль нь зөв бэ? Хоёулаа хэрэглэгддэг, нөхцөлөөс шалтгаална:

• Хувьсагч заавал байх ёстой (жишээ нь өгөгдлийн сангийн хаяг) — os.environ[...] ашиглах нь дээр, учир нь дутуу бол программ шууд, тодорхой унана. Чимээгүй ажиллаад дараа нь хачирхалтай алдаа өгөхөөс дээр.

• Хувьсагч заавал биш, боломжийн default байгаа бол — os.getenv(...) тохиромжтой.

Бид доор хоёуланг нь ашиглана.

.env файл гэж юу вэ

Environment variable-ыг гараар тохируулах нь төвөгтэй. Windows дээр систем тохиргооны цонх нээх, эсвэл терминал бүрд дахин зарлах шаардлагатай. Хөгжүүлэлтийн үед энэ нь уйтгартай.

Тиймээс .env файл гэсэн зуршил үүссэн. Энэ бол энгийн текст файл, төслийн хавтаст байрлана, дотор нь нэр-утгын хосууд:

API_KEY=нууц-түлхүүр-12345
APP_NAME=Тэмдэглэлийн API
DEBUG=true

Программ эхлэхэд энэ файлыг уншиж, доторх утгуудыг environment variable болгон ачаалдаг. Дараа нь код os.getenv(...)-ээр уншина.

Хамгийн чухал зүйл: .env файл кодтой хамт хуваалцагддаггүй. Түүнийг .gitignore-д оруулж, git-ээс хасдаг. Код нээлттэй, .env нууц.

.env файлыг унших ажлыг python-dotenv гэсэн сан хийдэг. Түүнийг суулгая.

Алхам 1: python-dotenv суулгах

Терминал дээр ((venv) идэвхтэй эсэхээ шалгаад):

pip install python-dotenv

Гаралт (ойролцоогоор):

Successfully installed python-dotenv-1.2.2

Хэрэв ModuleNotFoundError гарвал — venv идэвхтэй эсэхээ шалгаарай.

Алхам 2: .env файл үүсгэх

Төслийн үндсэн хавтаст (main.py-ийн хажууд) .env гэсэн файл үүсгэнэ. Нэр нь цэгээр эхэлж, өргөтгөлгүй — зөвхөн .env.

VS Code-ийн файлын жагсаалт дээр баруун товшоод New File, нэрийг .env гэнэ.

Дотор нь бичнэ:

API_KEY=нууц-түлхүүр-12345
APP_NAME=Тэмдэглэлийн API

Хадгална.

.env файлын дүрмүүд

Форматад хэдэн онцлог бий, тэдгээрийг мэдэх нь зүйтэй.

Хашилт хэрэггүй. API_KEY=нууц123 гэж бичнэ, API_KEY="нууц123" гэж биш. Хашилт бичвэл заримдаа утгын хэсэг болж орно.

Тэнцүүгийн тэмдгийн эргэн тойронд зай байхгүй. API_KEY=утга зөв; API_KEY = утга нь утгыг утга (эхэндээ зайтай) болгож болно.

Тайлбар #-ээр эхэлнэ:

# Энэ бол тайлбар
API_KEY=нууц-түлхүүр-12345

Нэр нь ихэвчлэн ТОМ ҮСГЭЭР бичигдэнэ — заавал биш, гэхдээ дэлхий нийтийн зуршил. API_KEY, DATABASE_URL, SECRET_KEY.

Бүх утга текст. DEBUG=true гэж бичихэд Python түүнийг "true" гэсэн текст гэж уншина, True гэсэн bool биш. Хөрвүүлэлтийг та өөрөө хийх ёстой. Энэ бол түгээмэл занга, доор дэлгэрэнгүй үзнэ.

Алхам 3: .gitignore — хамгийн чухал алхам

Одоо хамгийн чухал зүйл. .env файл хэзээ ч git-д орох ёсгүй.

Төслийн үндсэн хавтаст .gitignore гэсэн файл үүсгэнэ (байхгүй бол). Дотор нь бичнэ:

.env
venv/
__pycache__/
*.pyc

Хадгална.

.gitignore нь git-д "эдгээр файлыг үл ойшоо" гэж хэлдэг. .env мөр нь таны нууцыг хамгаална.

venv/ мөр нь виртуал орчныг хасна (тэр нь маш том бөгөөд дахин үүсгэж болдог). __pycache__/ болон *.pyc нь Python-ы түр зуурын файлууд.

Энэ алхмыг хэзээ ч бүү алгас. Хэрэв та энэ курсын кодыг GitHub-д байршуулах бол — .gitignore эхлээд байх ёстой. Нэг удаа commit хийсэн нууц түүхэнд үлддэг; урьдчилан сэргийлэх нь цорын ганц найдвартай арга.

Курс 2-т та git-тэй танилцаагүй бол энэ алхам зөвхөн урьдчилсан бэлтгэл гэж үзээрэй. Гэхдээ .gitignore файлыг одооноос үүсгэх нь дадал болгоход зүйтэй.

Алхам 4: Кодонд ачаалах

Одоо кодоо засна. main.py файлаа дараах кодоор солино:

python

# main.py
import os

from dotenv import load_dotenv
from fastapi import FastAPI, Depends, HTTPException, Header
from pydantic import BaseModel

load_dotenv()

API_KEY = os.environ["API_KEY"]
APP_NAME = os.getenv("APP_NAME", "API")

app = FastAPI(title=APP_NAME)

notes: list[dict] = []
next_id = 1


class NoteCreate(BaseModel):
    text: str
    done: bool = False


class NotePublic(BaseModel):
    id: int
    text: str
    done: bool


def verify_api_key(x_api_key: str = Header()):
    if x_api_key != API_KEY:
        raise HTTPException(status_code=403, detail="Түлхүүр буруу байна")
    return x_api_key


@app.get("/notes", response_model=list[NotePublic])
def get_notes():
    return notes


@app.post(
    "/notes",
    status_code=201,
    response_model=NotePublic,
    dependencies=[Depends(verify_api_key)],
)
def create_note(note: NoteCreate):
    global next_id
    new_note = note.model_dump()
    new_note["id"] = next_id
    notes.append(new_note)
    next_id += 1
    return new_note

Хадгална.

Кодын задаргаа

python

import os
from dotenv import load_dotenv

os — стандарт сан, environment variable уншина. load_dotenv — python-dotenv-ээс, .env файлыг ачаална.

python

load_dotenv()

Энэ мөр .env файлыг олж, уншиж, доторх утгуудыг environment variable болгон ачаална. Параметргүй дуудвал одоогийн хавтас (болон дээшээ) .env хайна.

Байрлал чухал. load_dotenv() нь os.environ-оос уншихаас өмнө дуудагдах ёстой. Эс бөгөөс хувьсагчид хараахан ачаалагдаагүй байна.

python

API_KEY = os.environ["API_KEY"]

os.environ[...] ашиглаж байна — учир нь API_KEY нь заавал. Хэрэв .env файлд байхгүй бол программ шууд унана, тодорхой алдаа өгнө. Энэ нь зөв: түлхүүргүй ажиллах нь утгагүй.

python

APP_NAME = os.getenv("APP_NAME", "API")

os.getenv(...) ашиглаж байна — учир нь APP_NAME нь заавал биш. Байхгүй бол "API" гэсэн default. Программ ажиллана.

Хоёр аргын ялгааг ухамсартай ашиглаж байгааг анзаараарай: заавал зүйлд os.environ, заавал бус зүйлд os.getenv.

Кодонд нууц үг байхгүй болсон. API_KEY хувьсагч байгаа боловч түүний утга нь .env-д. Кодыг хэн ч уншиж болно; түлхүүр тусдаа.

Туршина

Сервер reload болсныг шалгана. Хэрэв .env файл шинээр үүссэн бол серверийг гараар дахин асаах шаардлагатай байж болно (Ctrl+C, дараа нь fastapi dev main.py) — .env нь Python файл биш тул reload заримдаа түүнийг анзаардаггүй.

http://127.0.0.1:8000/docs

Дээд талд Тэмдэглэлийн API гэсэн гарчиг — .env-ээс уншсан APP_NAME.

POST /notes -> Try it out. x-api-key талбарт нууц-түлхүүр-12345 (.env-д байгаа утга), body-д:

json

{"text": "Тест"}

Server response (статус 201):

json

{"id":1,"text":"Тест","done":false}

Ажиллалаа. Түлхүүр .env-ээс уншигдаж, шалгалт өнгөрсөн.

Буруу түлхүүрээр — 403. Механизм өмнөх шигээ, зөвхөн эх сурвалж өөрчлөгдсөн.

Батлах: түлхүүрээ .env дээр солих

.env файлыг нээж, түлхүүрийг солино:

API_KEY=шинэ-түлхүүр-999
APP_NAME=Тэмдэглэлийн API

Хадгална. Дараа нь серверээ гараар дахин асаа (Ctrl+C, fastapi dev main.py) — .env өөрчлөлт reload-оор автоматаар ачаалагдахгүй.

Одоо хуучин түлхүүрээр POST илгээвэл — 403. Шинэ түлхүүрээр — 201.

Кодод гар хүрээгүйгээр тохиргоо өөрчлөгдлөө. Энэ бол environment variable-ийн гол давуу тал: тохиргоо солиход код өөрчлөгдөхгүй.

.env.example — багийн ажилд

Нэг практик асуудал: .env нь git-д ордоггүй тул шинэ хүн төслийг татаж авбал .env байхгүй, программ ажиллахгүй. Тэр хүн ямар хувьсагч хэрэгтэйг яаж мэдэх вэ?

Шийдэл нь .env.example гэсэн файл. Энэ нь .env-тэй ижил бүтэцтэй, гэхдээ бодит утгагүй:

API_KEY=энд-өөрийн-түлхүүрээ-бичнэ
APP_NAME=Тэмдэглэлийн API

Энэ файл git-д ордог (.gitignore-д байхгүй), учир нь нууц агуулаагүй. Шинэ хүн түүнийг хуулж, .env болгож нэрлээд, бодит утгуудаа бичнэ.

Энэ бол дэлхий нийтийн зуршил. Та GitHub дээр төсөл хараад .env.example файл байвал — энэ нь яг тэр зорилготой.

Хүсвэл одоо .env.example файл үүсгээрэй. Багаар ажиллахгүй бол заавал биш, гэхдээ дадал болгоход зүйтэй.

Занга: бүх утга текст

Дээр дурдсан занга руу эргэж орно. .env файл дахь бүх утга текст байдаг.

DEBUG=true
MAX_ITEMS=100

Кодонд:

python

debug = os.getenv("DEBUG")
max_items = os.getenv("MAX_ITEMS")

print(type(debug))      # <class 'str'>
print(type(max_items))  # <class 'str'>

debug нь "true" (текст), True биш. max_items нь "100" (текст), 100 биш.

Энэ нь ноцтой алдаа үүсгэж болно:

python

debug = os.getenv("DEBUG")     # "false"
if debug:
    print("Debug горим асаалттай")

"false" гэсэн текст нь Python-д үнэн утгатай (хоосон биш текст бүр үнэн). Тиймээс DEBUG=false гэж бичсэн ч debug горим асна. Ноцтой, олоход хэцүү алдаа.

Зөв хөрвүүлэлт:

python

debug = os.getenv("DEBUG", "false").lower() == "true"
max_items = int(os.getenv("MAX_ITEMS", "100"))

debug нь одоо жинхэнэ bool. max_items нь жинхэнэ тоо.

int(...) дотор default нь "100" (текст) байгааг анзаараарай — os.getenv нь текст буцаадаг тул default ч текст байх ёстой, дараа нь бүхэлд нь int() хийнэ.

Энэ занга нь бүх хэл, бүх framework-д байдаг. Environment variable үргэлж текст; хөрвүүлэлт таны ажил.

Түгээмэл алдаанууд

load_dotenv() дуудахгүй

python

import os
API_KEY = os.environ["API_KEY"]    # load_dotenv() байхгүй

Гаралт:

KeyError: 'API_KEY'

.env файл байгаа ч ачаалагдаагүй. load_dotenv()-ыг os.environ ашиглахаас өмнө дуудна.

.env файлын нэр буруу

env, .env.txt, env.txt — бүгд буруу. Нэр нь яг .env, цэгээр эхэлж, өргөтгөлгүй.

Windows дээр File Explorer-ээр файл үүсгэхэд өргөтгөл автоматаар нэмэгддэг тул VS Code-ийн файлын жагсаалт дээр үүсгэх нь илүү найдвартай.

.env-ийг git-д оруулах

.gitignore-д .env мөр байхгүй бол git түүнийг хянаж эхэлнэ. Нэг удаа commit хийсэн бол түүхэнд үлдэнэ.

Урьдчилан сэргийлэх нь цорын ганц найдвартай арга. .gitignore-ыг эхний өдөр үүсгэ.

Хашилт бичих

API_KEY="нууц-түлхүүр-12345"

Зарим тохиолдолд ажиллана, зарим тохиолдолд утга нь "нууц-түлхүүр-12345" (хашилттай) болно. Хашилтгүй бичих нь найдвартай.

Серверийг дахин асаахгүй

.env өөрчлөөд өөрчлөлт харагдахгүй бол — сервер .env-ийг дахин уншаагүй. fastapi dev нь Python файлыг ажигладаг, .env-ийг үргэлж биш. Ctrl+C, дараа нь дахин асаа.

Бодит production дээр яаж ажилладаг вэ

Нэг зүйлийг тодруулъя, учир нь энэ нь хожим ойлгомжтой байх ёстой.

.env файл бол хөгжүүлэлтийн тав тух. Бодит серверт (production) ихэвчлэн .env файл байдаггүй — оронд нь environment variable-ыг шууд тохируулдаг: хостинг үйлчилгээний тохиргооны хуудсанд, эсвэл серверийн тохиргоонд.

Гэхдээ код өөрчлөгдөхгүй. os.getenv("API_KEY") нь хоёр тохиолдолд ижил ажиллана — .env-ээс ирсэн ч, системээс ирсэн ч. load_dotenv() нь .env олдохгүй бол зүгээр л юу ч хийхгүй, алдаа өгөхгүй.

Энэ бол сайн зохион байгуулалтын шинж: нэг код, олон орчин. Бүлэг 15-т deployment ярихдаа бид үүн рүү эргэж ирнэ.

Туршаад үзээрэй

Хүсвэл .env-д шинэ хувьсагч нэмээд (жишээ нь MAX_NOTES=5), кодонд int()-ээр уншиж, тэмдэглэлийн тоог хязгаарлаж үзээрэй. Текстээс тоо руу хөрвүүлэх алхмыг гар дээрээ хийх нь зангыг сайн санагдуулна.

Сонирхвол .env файлаа түр зуур нэрээ өөрчлөөд (жишээ нь .env.backup), серверээ дахин асааж үзээрэй. KeyError: 'API_KEY' гарна — os.environ заавал хувьсагч дутуу бол хэрхэн шууд, тодорхой унахыг харна. Дараа нь нэрийг буцааж сольно.

Товч дүгнэлт

• Код ба тохиргоо тусдаа байх ёстой. Нууц кодонд байвал: хуваалцагдана, түүхэнд үлдэнэ, орчин бүрд өөр байж чадахгүй, солиход код өөрчлөгдөнө.

• Environment variable нь программын гаднаас, системээс өгөгддөг тохируулга.

• os.environ["NAME"] — заавал хувьсагчид (дутуу бол унана). os.getenv("NAME", "default") — заавал бусад.

• .env файл — хөгжүүлэлтийн тав тух: нэр-утгын хосууд, хашилтгүй, зайгүй, # тайлбар.

• pip install python-dotenv; кодонд load_dotenv() — os.environ ашиглахаас өмнө.

• .gitignore-д .env заавал байна. Урьдчилан сэргийлэх нь цорын ганц найдвартай арга.

• .env.example — бодит утгагүй загвар, git-д ордог, шинэ хүнд зориулагдсан.

• Занга: бүх утга текст. "false" нь Python-д үнэн. int(...), == "true" гэж хөрвүүл.

• .env өөрчлөвөл серверийг гараар дахин асаа.

• Production-д .env биш, системийн тохиргоо — гэхдээ код ижил хэвээр.

Таны нууц одоо кодоос гарлаа. Дараагийн хичээлд бид алдааны хариугаа өөриймсүүлнэ: FastAPI-ийн стандарт {"detail": "..."} бүтцээс өөр, өөрийн API-д тохирсон тогтвортой алдааны хэлбэр үүсгэж сурна. Тэр нь Бүлэг 9-ийн сүүлчийн ойлголт бөгөөд түүний дараа бид Түвшин 3-ын бүтээн байгуулалт — Тэмдэглэлийн API v2 руу орно, тэнд энэ бүлэг болон Бүлэг 7-8-ын бүх зүйл нэгдэх болно.