Lua Academy · Lekcja

xpcall i programy obsługi komunikatów

Proszę używać xpcall z niestandardowym programem obsługi do uzyskiwania szczegółowych śladów stosu błędów.

xpcall i programy obsługi komunikatów to bezpłatna lekcja Lua Academy na CoddyKit. To lekcja 3 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej Lua Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs Lua Academy zawiera 4 lekcji w sumie.

Składnia xpcall

xpcall(f, handler, ...) wywołuje f z argumentami ... w trybie chronionym, a w przypadku błędu wywołuje handler(errorObject). Wartość zwrócona przez moduł obsługi staje się drugą wartością zwracaną przez xpcall. W przeciwieństwie do pcall, xpcall uruchamia moduł obsługi, gdy stos jest jeszcze nienaruszony.

local function handler(err)
  return "HANDLED: " .. tostring(err)
end

local ok, msg = xpcall(
  function() error("something bad") end,
  handler
)

print(ok)   -- false
print(msg)  -- HANDLED: ...: something bad

debug.traceback jako moduł obsługi

Najczęściej używanym modułem obsługi xpcall jest debug.traceback. Należy przekazać go bezpośrednio jako moduł obsługi — formatuje błąd wraz z pełnym śladem stosu wywołań, co jest niezwykle cenne podczas debugowania błędów w środowisku produkcyjnym.

local function level3() error("deep error") end
local function level2() level3() end
local function level1() level2() end

local ok, err = xpcall(level1, debug.traceback)

if not ok then
  -- err contains the full stack trace
  print(err)
end

Własny moduł obsługi z kontekstem

Własny moduł obsługi może dodać kontekst: znacznik czasu, zapis do pliku lub powiadomienie systemów monitorowania, a następnie zwrócić sformatowany błąd. Jest to standardowy wzorzec obsługi błędów w aplikacjach Lua działających w środowisku produkcyjnym.

local function errorHandler(err)
  local trace = debug.traceback(err, 2)
  local ts = os.date("%H:%M:%S")
  local report = string.format("[%s] ERROR\n%s", ts, trace)
  -- Could log to file here
  io.stderr:write(report .. "\n")
  return report
end

local ok, msg = xpcall(
  function()
    local t = nil
    return t.field   -- error!
  end,
  errorHandler
)
print("ok:", ok)

Moduł obsługi nie może zgłaszać błędów

Jeśli sam moduł obsługi komunikatów zgłosi błąd, Lua zwróci wskaźnik błędu bez ponownego wywoływania modułu obsługi. Moduły obsługi należy zawsze pisać tak, aby były odporne na błędy — bez operacji wejścia-wyjścia, które mogą się nie powieść, i bez indeksowania wartości nil.

local function safeHandler(err)
  -- Keep handler simple and safe
  local ok, trace = pcall(debug.traceback, err, 2)
  if ok then return trace
  else return tostring(err) .. " (traceback failed)"
  end
end

local ok, msg = xpcall(
  function() error({complex="error table"}) end,
  safeHandler
)
print(ok, type(msg))

xpcall dla pętli głównej

W programach działających długo (serwerach, pętlach gier) należy opakować główną funkcję w xpcall, aby przechwytywać i rejestrować nieobsłużone błędy bez awarii programu. Pętla główna może wtedy zdecydować, czy uruchomić program ponownie, czy go zakończyć.

local function mainApp()
  -- simulate work
  for i = 1, 3 do
    print("Tick", i)
    if i == 2 then error("transient error") end
  end
end

local function handler(e)
  return debug.traceback("App error: "..tostring(e), 2)
end

local ok, err = xpcall(mainApp, handler)
if not ok then
  print("Application crashed:\n" .. err)
end

Ustrukturyzowane zgłaszanie błędów

Połączenie xpcall z ustrukturyzowanymi obiektami błędów i rozbudowanym modułem obsługi pozwala tworzyć szczegółowe, praktyczne raporty błędów na potrzeby debugowania lub pulpitów monitorowania.

local function handler(err)
  local info = {
    error   = tostring(err),
    time    = os.date("!%Y-%m-%dT%H:%M:%SZ"),
    trace   = debug.traceback(nil, 2),
  }
  return info
end

local ok, report = xpcall(
  function() error({code=500, msg="internal error"}) end,
  handler
)

if not ok then
  print("Time:", report.time)
  print("Error:", report.error)
  -- print("Trace:", report.trace)
end

xpcall dla coroutine

Wewnątrz coroutine pcall działa normalnie. Aby uzyskać ślady stosu dla błędów występujących w coroutine, należy opakować jej ciało w xpcall. Moduł obsługi działa w kontekście stosu coroutine.

local function co_body()
  error("error inside coroutine")
end

local co = coroutine.create(function()
  local ok, err = xpcall(co_body, debug.traceback)
  if not ok then
    print("Caught in coroutine:", err:match("([^\n]+)"))
  end
end)

coroutine.resume(co)

Wzbogacanie obiektów błędów

Moduł obsługi może przekształcić zwykły błąd tekstowy w rozbudowany obiekt albo jeszcze bardziej wzbogacić już rozbudowany obiekt. Dzięki temu kod niższego poziomu może zgłaszać proste błędy, a moduł obsługi dodaje kontekst (identyfikator żądania, sesję użytkownika, informacje o środowisku).

local requestID = "req-123"

local function handler(err)
  if type(err) == "string" then
    return {message=err, requestID=requestID, level="error"}
  end
  err.requestID = requestID
  return err
end

local ok, result = xpcall(
  function() error("database timeout") end,
  handler
)

if not ok then
  print(result.message, result.requestID)
  -- database timeout  req-123
end

Porównanie pcall i xpcall

Proszę użyć pcall, gdy: potrzebna jest tylko wartość błędu, błąd jest oczekiwany i obsługiwany lokalnie albo ważna jest prostota. Proszę użyć xpcall, gdy: potrzebne są ślady stosu, kod działa na granicy systemu lub chcą Państwo dodawać kontekst do wszystkich błędów.

-- pcall: simple, no overhead
local ok, err = pcall(function()
  return 1/0   -- no error in Lua! returns inf
end)
print(ok, err)   -- true  inf

-- xpcall: adds traceback
local ok2, err2 = xpcall(
  function() error("real error") end,
  debug.traceback
)
print(ok2)       -- false
print(err2:sub(1,40))  -- first line of traceback

Wartość zwracana przez moduł obsługi

To, co zwraca moduł obsługi, staje się drugą wartością zwracaną przez xpcall. Jeśli moduł obsługi zwróci nil, druga wartość zwracana przez xpcall również będzie nil. Najbardziej elastyczne rozwiązanie polega na zwróceniu przez moduł obsługi oryginalnego obiektu błędu wraz z dodatkowymi informacjami.

local function enrichedHandler(err)
  return {
    original = err,
    traceback = debug.traceback(nil, 2),
    timestamp = os.time(),
  }
end

local ok, report = xpcall(
  function() error("oops") end,
  enrichedHandler
)

if not ok then
  print(type(report))          -- table
  print(report.original)       -- ...: oops
  print(report.timestamp > 0)  -- true
end

Szybkie sprawdzenie

Jaka jest najważniejsza zaleta xpcall w porównaniu z pcall?

Podsumowanie: xpcall

Podsumowanie:

xpcall(f, handler, ...) — moduł obsługi działa, gdy stos jest jeszcze nienaruszony
Należy użyć debug.traceback jako modułu obsługi, aby uzyskać pełne ślady stosu
Moduł obsługi nie może zgłaszać błędów — powinien być prosty
W module obsługi należy wzbogacać błędy o kontekst
Pętle główne i moduły obsługi serwera należy opakować w xpcall
Wartość zwracana przez moduł obsługi staje się drugą wartością zwracaną przez xpcall

Często zadawane pytania

Czy lekcja „xpcall i programy obsługi komunikatów” jest bezpłatna?

Tak — pełny tekst „xpcall i programy obsługi komunikatów” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu Lua Academy, przejdź na CoddyKit PRO. Kurs Lua Academy zawiera 4 lekcji w sumie.

Co nauczysz się w „xpcall i programy obsługi komunikatów”?

Proszę używać xpcall z niestandardowym programem obsługi do uzyskiwania szczegółowych śladów stosu błędów. Ćwiczysz Lua Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.

Czy potrzebuję doświadczenia, aby zacząć Lua Academy?

Nie wymagamy żadnego doświadczenia. Lua Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 3 z 4.

Ile czasu zajmuje lekcja „xpcall i programy obsługi komunikatów”?

Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.

Czy mogę pisać i uruchamiać kod w tej lekcji Lua Academy?

Tak. Każda lekcja Lua Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.

Wszystkie lekcje w tym kursie

← Powrót do Lua Academy