وثائق Go قابلة للتشغيل: قراءة الملفات وكتابتها

Q: كيف أقرأ ملفًا كاملًا إلى نص في Go؟

تعيد data, err := os.ReadFile("notes.txt") المحتوى كـ []byte؛ حوّله بـ string(data). تفتح الملف وتقرؤه وتغلقه نيابة عنك. استخدمها للملفات التي تتّسع لها الذاكرة بسهولة؛ أما الملفات الكبيرة فاقرأها سطرًا بسطر بـ bufio.Scanner.

Q: كيف أقرأ ملفًا سطرًا بسطر في Go؟

افتح الملف بـ os.Open، ثم defer f.Close()، وغلّفه بـ bufio.NewScanner(f)، ودُر في حلقة for sc.Scan() { line := sc.Text() }، وافحص sc.Err() بعد الحلقة. الأسطر الأطول من 64 KB تجعل الماسح يفشل برسالة token too long ما لم تكبّر مخزنه بـ sc.Buffer.

Q: كيف ألحق نصًا بملف في Go؟

افتحه بـ os.OpenFile(name, os.OAPPEND|os.OCREATE|os.OWRONLY, 0o644)، واكتب، وافحص الخطأ الصادر عن Close. ينشئ OCREATE الملف إن لم يكن موجودًا، ويجعل O_APPEND كل كتابة تذهب إلى النهاية.

Q: كيف أتحقّق من وجود ملف في Go؟

استدعِ os.Stat(path) وافحص الخطأ بـ errors.Is(err, fs.ErrNotExist). الخطأ nil يعني أنه موجود. أي خطأ آخر (رفض الصلاحية مثلًا) يعني أنك لا تستطيع الجزم، فعالجه على حدة بدل معاملته كـ "غير موجود".

قراءة ملف كامل وكتابته

تغطّي os.WriteFile وos.ReadFile معظم الحاجات. تفتحان وتكتبان أو تقرآن وتغلقان في استدعاء واحد.

package main

import (
	"fmt"
	"os"
	"path/filepath"
)

func main() {
	dir, err := os.MkdirTemp("", "demo")
	if err != nil {
		fmt.Println(err)
		return
	}
	defer os.RemoveAll(dir) // clean up everything at the end

	path := filepath.Join(dir, "greeting.txt")

	if err := os.WriteFile(path, []byte("hello, file\nsecond line\n"), 0o644); err != nil {
		fmt.Println("write:", err)
		return
	}

	data, err := os.ReadFile(path)
	if err != nil {
		fmt.Println("read:", err)
		return
	}
	fmt.Print(string(data))
	fmt.Println("bytes:", len(data))
}

تعمل أمثلة هذه الصفحة في مجلد مؤقّت من os.MkdirTemp وتحذفه بـ defer os.RemoveAll(dir)، فلا تترك أثرًا. في شيفرتك يُحلّ المسار النسبي مثل "config.json" نسبة إلى مجلد العمل للعملية، وهو ليس بالضرورة مجلد الملف المصدري أو الملف التنفيذي.

تنشئ os.WriteFile الملف عند الحاجة وتفرّغه إن كان موجودًا. الوسيط الثالث صلاحية Unix للملف المنشأ حديثًا: 0o644 تعني أن المالك يقرأ ويكتب، والبقية يقرؤون. ويُتجاهل للملف الموجود مسبقًا، وقد يزيل umask العملية بعض البتات.

تقرأ os.ReadFile كل شيء إلى الذاكرة. هذا صحيح لملفات الإعدادات والمدخلات الصغيرة، وخاطئ لسجل بحجم عدة غيغابايت.

القراءة سطرًا بسطر بـ bufio.Scanner

للملفات الكبيرة، أو عندما تريد الأسطر أصلًا، استخدم bufio.Scanner. يقرأ على دفعات ويسلّمك سطرًا في كل مرة، دون محرف السطر الجديد.

package main

import (
	"bufio"
	"fmt"
	"os"
	"strings"
)

func main() {
	f, err := os.CreateTemp("", "log-*.txt")
	if err != nil {
		fmt.Println(err)
		return
	}
	defer os.Remove(f.Name())
	fmt.Fprintln(f, "INFO started")
	fmt.Fprintln(f, "ERROR disk full")
	fmt.Fprintln(f, "INFO retrying")
	fmt.Fprintln(f, "ERROR disk still full")
	f.Close()

	in, err := os.Open(f.Name())
	if err != nil {
		fmt.Println(err)
		return
	}
	defer in.Close()

	sc := bufio.NewScanner(in)
	lineNo, errorsSeen := 0, 0
	for sc.Scan() {
		lineNo++
		line := sc.Text()
		if strings.HasPrefix(line, "ERROR") {
			errorsSeen++
			fmt.Printf("line %d: %s\n", lineNo, line)
		}
	}
	if err := sc.Err(); err != nil { // Scan returns false on errors too
		fmt.Println("scan:", err)
		return
	}
	fmt.Println("errors:", errorsSeen, "of", lineNo, "lines")
}

ثلاث تفاصيل:

افحص sc.Err() بعد الحلقة. تعيد Scan القيمة false عند نهاية الملف وعند الخطأ على حد سواء، وErr وحدها تميّز بينهما.
حد السطر 64 KB. افتراضيًا يوقف السطر الواحد الأطول من 64 KB الماسح برسالة bufio.Scanner: token too long. للملفات ذات الأسطر الطويلة (JSON مضغوط، وبعض السجلات) ارفع الحد قبل الحلقة: sc.Buffer(make([]byte, 1024*1024), 10*1024*1024).
وحدات أخرى. يعطي sc.Split(bufio.ScanWords) كلمات؛ ويعطي bufio.ScanRunes أحرفًا.

لقراءة تدفّق على دفعات ثابتة الحجم بدل الأسطر، استخدم f.Read(buf) في حلقة أو io.Copy إلى كاتب آخر.

الكتابة: os.Create وos.OpenFile والإلحاق

تفتح os.Create(name) ملفًا للكتابة، فتنشئه أو تفرّغه. وتعطي os.OpenFile تحكّمًا كاملًا عبر الأعلام:

العلم	المعنى
`os.O_RDONLY`، `os.O_WRONLY`، `os.O_RDWR`	الفتح للقراءة أو الكتابة أو كليهما (اختر واحدًا)
`os.O_CREATE`	إنشاء الملف إن لم يكن موجودًا
`os.O_TRUNC`	تفريغ الملف عند فتحه
`os.O_APPEND`	كل كتابة تذهب إلى النهاية
`os.O_EXCL`	مع `O_CREATE`: الفشل إذا كان الملف موجودًا مسبقًا

os.Open(name) تساوي OpenFile(name, O_RDONLY, 0). وos.Create(name) تساوي OpenFile(name, O_RDWR|O_CREATE|O_TRUNC, 0o666).

package main

import (
	"bufio"
	"fmt"
	"os"
	"path/filepath"
)

func appendLine(path, line string) error {
	f, err := os.OpenFile(path, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)
	if err != nil {
		return err
	}
	if _, err := fmt.Fprintln(f, line); err != nil {
		f.Close()
		return err
	}
	return f.Close() // Close can report a failed write: return its error
}

func main() {
	dir, err := os.MkdirTemp("", "append")
	if err != nil {
		fmt.Println(err)
		return
	}
	defer os.RemoveAll(dir)
	path := filepath.Join(dir, "audit.log")

	for _, msg := range []string{"login alice", "upload report.pdf", "logout alice"} {
		if err := appendLine(path, msg); err != nil {
			fmt.Println("append:", err)
			return
		}
	}

	// Buffered writing: many small writes, one syscall per buffer.
	out, err := os.Create(filepath.Join(dir, "numbers.txt"))
	if err != nil {
		fmt.Println(err)
		return
	}
	w := bufio.NewWriter(out)
	for i := 1; i <= 1000; i++ {
		fmt.Fprintln(w, i)
	}
	if err := w.Flush(); err != nil { // without Flush the tail of the data is lost
		fmt.Println("flush:", err)
	}
	if err := out.Close(); err != nil {
		fmt.Println("close:", err)
	}

	data, _ := os.ReadFile(path)
	fmt.Print(string(data))
	info, _ := os.Stat(filepath.Join(dir, "numbers.txt"))
	fmt.Println("numbers.txt size:", info.Size(), "bytes")
}

عند الكتابة يهمّ الخطأ الصادر عن Close. بعض أنظمة الملفات لا تبلغ عن فشل الكتابة إلا وقت الإغلاق، فقد تخفي defer f.Close() وحدها بيانات ضائعة. للملفات التي تكتب فيها افحص Close صراحة كما تفعل appendLine. وللملفات التي تقرؤها فقط لا بأس بـ defer f.Close().

تقبل fmt.Fprintln وبقية دوال الطباعة في fmt أي io.Writer، ومنها الملف. يجمّع bufio.Writer الكتابات الصغيرة في الذاكرة. نسيان w.Flush() خطأ كلاسيكي: يخرج البرنامج بشكل طبيعي ولا تصل الكيلوبايتات الأخيرة إلى الملف أبدًا.

هل الملف موجود؟

لا تملك Go دالة os.Exists. استدعِ os.Stat وافحص الخطأ:

package main

import (
	"errors"
	"fmt"
	"io/fs"
	"os"
	"path/filepath"
)

func exists(path string) (bool, error) {
	_, err := os.Stat(path)
	if err == nil {
		return true, nil
	}
	if errors.Is(err, fs.ErrNotExist) {
		return false, nil
	}
	return false, err // permission denied, broken mount, ...: unknown
}

func main() {
	dir, err := os.MkdirTemp("", "exists")
	if err != nil {
		fmt.Println(err)
		return
	}
	defer os.RemoveAll(dir)

	fmt.Println(exists(dir))
	fmt.Println(exists(filepath.Join(dir, "nope.txt")))

	_, err = os.ReadFile(filepath.Join(dir, "nope.txt"))
	fmt.Println("not exist:", errors.Is(err, fs.ErrNotExist))
	fmt.Println(err)
}

errors.Is(err, fs.ErrNotExist) هو الأسلوب المعتمد حاليًا. يحلّ محل os.IsNotExist(err) الأقدم، الذي لا يرى عبر الأخطاء المغلّفة.

الفحص قبل الفتح غالبًا غير ضروري ومعرّض للتسابق: قد يظهر الملف أو يختفي بين الفحص والفتح. عادة تفتحه مباشرة وتعالج fs.ErrNotExist الصادر عن الفتح. لإنشاء ملف فقط إن لم يكن موجودًا بعد، استخدم O_CREATE|O_EXCL، الذي يجعل الفحص والإنشاء خطوة ذرّية واحدة.

المجلدات

package main

import (
	"fmt"
	"io/fs"
	"os"
	"path/filepath"
)

func main() {
	root, err := os.MkdirTemp("", "tree")
	if err != nil {
		fmt.Println(err)
		return
	}
	defer os.RemoveAll(root)

	// MkdirAll creates every missing parent, like mkdir -p.
	if err := os.MkdirAll(filepath.Join(root, "src", "util"), 0o755); err != nil {
		fmt.Println(err)
		return
	}
	for _, name := range []string{"main.go", "src/app.go", "src/util/strings.go", "README.md"} {
		if err := os.WriteFile(filepath.Join(root, name), []byte("x"), 0o644); err != nil {
			fmt.Println(err)
			return
		}
	}

	// One level: ReadDir returns entries sorted by name.
	entries, err := os.ReadDir(root)
	if err != nil {
		fmt.Println(err)
		return
	}
	for _, e := range entries {
		fmt.Printf("%-10s dir=%v\n", e.Name(), e.IsDir())
	}

	// Recursive: WalkDir visits every file and directory in lexical order.
	fmt.Println("Go files:")
	err = filepath.WalkDir(root, func(path string, d fs.DirEntry, err error) error {
		if err != nil {
			return err
		}
		if !d.IsDir() && filepath.Ext(path) == ".go" {
			rel, _ := filepath.Rel(root, path)
			fmt.Println(" ", filepath.ToSlash(rel))
		}
		return nil
	})
	if err != nil {
		fmt.Println(err)
	}

	// Glob matches one directory level against a pattern.
	matches, _ := filepath.Glob(filepath.Join(root, "*.md"))
	fmt.Println("markdown files:", len(matches))
}

المهمة	الدالة
إنشاء مجلد واحد	`os.Mkdir(path, 0o755)`
إنشاء مسار مع آبائه	`os.MkdirAll(path, 0o755)`
سرد محتوى مجلد	`os.ReadDir(path)`
المرور على شجرة	`filepath.WalkDir(root, fn)`
حذف ملف أو مجلد فارغ	`os.Remove(path)`
حذف شجرة	`os.RemoveAll(path)`
إعادة التسمية أو النقل	`os.Rename(old, new)`
ملف أو مجلد مؤقّت	`os.CreateTemp("", "prefix-*")`، `os.MkdirTemp("", "prefix")`
ضمّ أجزاء المسار	`filepath.Join(a, b, c)`

استخدم path/filepath لمسارات نظام الملفات: فهي تستخدم الفاصل الصحيح لنظام التشغيل (\ في Windows). أما الحزمة path فللمسارات المفصولة بشرطة مائلة مثل عناوين URL.

أضافت Go 1.24 أيضًا os.Root (os.OpenRoot(dir))، الذي يفتح الملفات داخل مجلد واحد فقط ويرفض المسارات التي تخرج منه بـ .. أو بالروابط الرمزية. استخدمه عندما تأتي أسماء الملفات من المستخدمين.

أخطاء شائعة

عدم فحص الأخطاء. كل واحد من هذه الاستدعاءات قد يفشل. الملف الذي فشل فتحه يكون nil، وكل Read أو Write أو Close لاحقة عليه تعيد invalid argument، فتخفي السبب الحقيقي (الملف مفقود، أو الصلاحية مرفوضة).
نسيان sc.Err() بعد حلقة المسح. يبدو خطأ القراءة كنهاية الملف.
نسيان Flush على bufio.Writer. تنقص نهاية الملف.
تجاهل الخطأ الصادر عن Close بعد الكتابة. قد لا تظهر أخطاء الكتابة إلا هناك.
defer f.Close() داخل حلقة على ملفات كثيرة. تبقى الملفات مفتوحة حتى تعود الدالة وقد تنفد واصفات الملفات. انقل جسم الحلقة إلى دالة ليُغلق كل ملف في تكراره.
كتابة الصلاحيات بالنظام العشري. 644 ليست 0o644. تقرأ Go القيمة 644 كرقم عشري، أي 0o1204، فتضبط بتات غريبة.

الأسئلة الشائعة

كيف أقرأ ملفًا كاملًا إلى نص في Go؟

تعيد data, err := os.ReadFile("notes.txt") المحتوى كـ []byte؛ حوّله بـ string(data). تفتح الملف وتقرؤه وتغلقه نيابة عنك. استخدمها للملفات التي تتّسع لها الذاكرة بسهولة؛ أما الملفات الكبيرة فاقرأها سطرًا بسطر بـ bufio.Scanner.

كيف أقرأ ملفًا سطرًا بسطر في Go؟

افتح الملف بـ os.Open، ثم defer f.Close()، وغلّفه بـ bufio.NewScanner(f)، ودُر في حلقة for sc.Scan() { line := sc.Text() }، وافحص sc.Err() بعد الحلقة. الأسطر الأطول من 64 KB تجعل الماسح يفشل برسالة token too long ما لم تكبّر مخزنه بـ sc.Buffer.

كيف ألحق نصًا بملف في Go؟

افتحه بـ os.OpenFile(name, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0o644)، واكتب، وافحص الخطأ الصادر عن Close. ينشئ O_CREATE الملف إن لم يكن موجودًا، ويجعل O_APPEND كل كتابة تذهب إلى النهاية.

كيف أتحقّق من وجود ملف في Go؟

استدعِ os.Stat(path) وافحص الخطأ بـ errors.Is(err, fs.ErrNotExist). الخطأ nil يعني أنه موجود. أي خطأ آخر (رفض الصلاحية مثلًا) يعني أنك لا تستطيع الجزم، فعالجه على حدة بدل معاملته كـ "غير موجود".

مفاهيم ذات صلة