小型文件数据库 (a file database for small apps) SharpFileDB

小型文件数据库 (a file database for small apps) SharpFileDB

For english version of this article, please click here.

我并不擅长数据库，如有不当之处，请多多指教。

本文参考了（http://www.cnblogs.com/gaochundong/archive/2013/04/24/csharp_file_database.html），在此表示感谢！

目标(Goal)

我决定做一个以支持小型应用（万人级别）为目标的数据库。

既然是小型的数据库，那么最好不要依赖其它驱动、工具包，免得拖泥带水难以实施。

完全用C#编写成DLL，易学易用。

支持CRUD（增加(Create)、读取(Retrieve)、更新(Update)和删除(Delete)）。

不使用SQL，客观原因我不擅长SQL，主观原因我不喜欢SQL，情景原因没有必要。

直接用文本文件或二进制文件存储数据。开发时用文本文件，便于调试；发布时用二进制文件，比较安全。

简单来说，就是纯C#、小型、无SQL。此类库就命名为SharpFileDB。

为了便于共同开发，我把这个项目放到Github上，并且所有类库代码的注释都是中英文双语的。中文便于理解，英文便于今后国际化。也许我想的太多了。

设计草图(sketch)

使用场景(User Scene)

SharpFileDB库的典型使用场景如下。

                // common cases to use SharpFileDB.
                FileDBContext db = new FileDBContext();

                Cat cat = new Cat();
                cat.Name = "xiao xiao bai";
                db.Create(cat);

                Predicate<Cat> pre = new Predicate<Cat>(x => x.Name == "xiao xiao bai");
                IList<Cat> cats = db.Retrieve(pre);

                cat.Name = "xiao bai";
                db.Update(cat);

                db.Delete(cat);

这个场景里包含了创建数据库和使用CRUD操作的情形。

我们就从这个使用场景开始设计出第一版最简单的一个文件数据库。

核心概念(Core Concepts)

如下图所示，数据库有三个核心的东西：数据库上下文，就是数据库本身，能够执行CRUD操作；表，在这里是一个个文件，用一个FileObject类型表示一个表；持久化工具，实现CRUD操作，把信息存储到数据库中。

表vs类型(Table vs Type)

为方便叙述，下面我们以Cat为例进行说明。

    /// <summary>
    /// demo file object
    /// </summary>
    public class Cat : FileObject
    {
        public string Name { get; set; }
        public int Legs { get; set; }

        public override string ToString()
        {
            return string.Format("{0}, Name: {1}, Legs: {2}", base.ToString(), Name, Legs);
        }
    }

Cat这个类型就等价于关系数据库里的一个Table。

Cat的一个实例，就等价于关系数据库的Table里的一条记录。

以后我们把这样的类型称为表类型。

全局唯一的主键(global unique main key)

类似关系数据库的主键，我们需要用全局唯一的Id来区分每个对象。每个表类型的实例都需要这样一个Id，那么我们就用一个abstract基类做这件事。

    /// <summary>
    /// 可在文件数据库中使用CRUD操作的所有类型的基类。
    /// Base class for all classed that can use CRUD in SharpFileDB.
    /// </summary>
    [Serializable]
    public abstract class FileObject
    {
        /// <summary>
        /// 主键.
        /// main key.
        /// </summary>
        public Guid Id { get; set; }

        /// <summary>
        /// 创建一个文件对象，并自动为其生成一个全局唯一的Id。
        /// <para>Create a <see cref="FileObject"/> and generate a global unique id for it.</para>
        /// </summary>
        public FileObject()
        {
            this.Id = Guid.NewGuid();
        }

        public override string ToString()
        {
            return string.Format("Id: {0}", this.Id);
        }
    }

 

数据库(FileDBContext)

一个数据库上下文负责各种类型的文件对象的CRUD操作。

    /// <summary>
/// 文件数据库。
    /// Represents a file database.
    /// </summary>
    public class FileDBContext
    {
        #region Fields

        /// <summary>
        /// 文件数据库操作锁
        /// <para>database operation lock.</para>
        /// </summary>
        protected static readonly object operationLock = new object();

        /// <summary>
        /// 文件数据库
        /// <para>Represents a file database.</para>
        /// </summary>
        /// <param name="directory">数据库文件所在目录<para>Directory for all files of database.</para></param>
        public FileDBContext(string directory = null)
        {
            if (directory == null)
            {
                this.Directory = Environment.CurrentDirectory;
            }
            else
            {
                Directory = directory;
            }
        }

        #endregion

        public override string ToString()
        {
            return string.Format("@: {0}", Directory);
        }

        #region Properties

        /// <summary>
        /// 数据库文件所在目录
        /// <para>Directory of database files.</para>
        /// </summary>
        public virtual string Directory { get; protected set; }

        #endregion


        protected string Serialize(FileObject item)
        {
            using (StringWriterWithEncoding sw = new StringWriterWithEncoding(Encoding.UTF8))
            {
                XmlSerializer serializer = new XmlSerializer(item.GetType());
                serializer.Serialize(sw, item);
                string serializedString = sw.ToString();

                return serializedString;
            }
        }

        /// <summary>
        /// 将字符串反序列化成文档对象
        /// </summary>
        /// <typeparam name="TDocument">文档类型</typeparam>
        /// <param name="serializedFileObject">字符串</param>
        /// <returns>
        /// 文档对象
        /// </returns>
        protected TFileObject Deserialize<TFileObject>(string serializedFileObject)
            where TFileObject : FileObject
        {
            if (string.IsNullOrEmpty(serializedFileObject))
                throw new ArgumentNullException("data");

            using (StringReader sr = new StringReader(serializedFileObject))
            {
                XmlSerializer serializer = new XmlSerializer(typeof(TFileObject));
                object deserializedObj = serializer.Deserialize(sr);
                TFileObject fileObject = deserializedObj as TFileObject;
                return fileObject;
            }
        }

        protected string GenerateFileFullPath(FileObject item)
        {
            string path = GenerateFilePath(item.GetType());
            string name = item.GenerateFileName();
            string fullname = Path.Combine(path, name);
            return fullname;
        }

        /// <summary>
        /// 生成文件路径
        /// </summary>
        /// <typeparam name="TDocument">文档类型</typeparam>
        /// <returns>文件路径</returns>
        protected string GenerateFilePath(Type type)
        {
            string path = Path.Combine(this.Directory, type.Name);
            return path;
        }

        #region CRUD

        /// <summary>
        /// 增加一个<see cref="FileObject"/>到数据库。这实际上创建了一个文件。
        /// <para>Create a new <see cref="FileObject"/> into database. This operation will create a new file.</para>
        /// </summary>
        /// <param name="item"></param>
        public virtual void Create(FileObject item)
        {
            string fileName = GenerateFileFullPath(item);
            string output = Serialize(item);

            lock (operationLock)
            {
                System.IO.FileInfo info = new System.IO.FileInfo(fileName);
                System.IO.Directory.CreateDirectory(info.Directory.FullName);
                System.IO.File.WriteAllText(fileName, output);
            }
        }

        /// <summary>
        /// 检索符合给定条件的所有<paramref name="TFileObject"/>。
        /// <para>Retrives all <paramref name="TFileObject"/> that satisfies the specified condition.</para>
        /// </summary>
        /// <typeparam name="TFileObject"></typeparam>
        /// <param name="predicate">检索出的对象应满足的条件。<para>THe condition that should be satisfied by retrived object.</para></param>
        /// <returns></returns>
        public virtual IList<TFileObject> Retrieve<TFileObject>(Predicate<TFileObject> predicate)
            where TFileObject : FileObject
        {
            IList<TFileObject> result = new List<TFileObject>();
            if (predicate != null)
            {
                string path = GenerateFilePath(typeof(TFileObject));
                string[] files = System.IO.Directory.GetFiles(path, "*.xml", SearchOption.AllDirectories);
                foreach (var item in files)
                {
                    string fileContent = File.ReadAllText(item);
                    TFileObject deserializedFileObject = Deserialize<TFileObject>(fileContent);
                    if (predicate(deserializedFileObject))
                    {
                        result.Add(deserializedFileObject);
                    }
                }
            }

            return result;
        }

        /// <summary>
        /// 更新给定的对象。
        /// <para>Update specified <paramref name="FileObject"/>.</para>
        /// </summary>
        /// <param name="item">要被更新的对象。<para>The object to be updated.</para></param>
        public virtual void Update(FileObject item)
        {
            string fileName = GenerateFileFullPath(item);
            string output = Serialize(item);

            lock (operationLock)
            {
                System.IO.FileInfo info = new System.IO.FileInfo(fileName);
                System.IO.Directory.CreateDirectory(info.Directory.FullName);
                System.IO.File.WriteAllText(fileName, output);
            }
        }

        /// <summary>
        /// 删除指定的对象。
        /// <para>Delete specified <paramref name="FileObject"/>.</para>
        /// </summary>
        /// <param name="item">要被删除的对象。<para>The object to be deleted.</para></param>
        public virtual void Delete(FileObject item)
        {
            if (item == null)
            {
                throw new ArgumentNullException(item.ToString());
            }

            string filename = GenerateFileFullPath(item);
            if (File.Exists(filename))
            {
                lock (operationLock)
                {
                    File.Delete(filename);
                }
            }
        }

        #endregion CRUD

    }

 

文件存储方式(Way to store files)

在数据库目录下，SharpFileDB为每个表类型创建一个文件夹，在各自文件夹内存储每个对象。每个对象都占用一个XML文件。暂时用XML格式，因为是.NET内置的格式，省的再找外部序列化工具。XML文件名与其对应的对象Id相同。

下载(Download)

我已将源码放到（https://github.com/bitzhuwei/SharpFileDB/），欢迎试用、提建议或Fork此项目。

更新(Update)

2015-06-22

增加了序列化接口(IPersistence)，使得FileDBContext可以选择序列化器。

增加了二进制序列化类型(BinaryPersistence)。

使用Convert.ToBase64String()和Convert.FromBase64String()实现Byte数组与string之间的转换。

//Image-->Byte[]-->String 
 Byte[] bytes = File.ReadAllBytes(@"d:a.gif"); 
 MemoryStream ms = new MemoryStream(bty); 
 String imgStr = Convert.ToBase64String(ms.ToArray());

//String-->Byte[]-->Image 
 byte[] imgBytes = Convert.FromBase64String(imgStr); 
 Response.BinaryWrite(imgBytes.ToArray());  // 将一个二制字符串写入HTTP输出流

修改了接口IPersistence，让它直接进行内存数据与文件之间的转化。这样，即使序列化的结果是byte[]或其它类型，也可以直接保存到文件，不再需要先转化为string后再保存。

    /// <summary>
    /// 文件数据库使用此接口进行持久化相关的操作。
    /// <para>File database executes persistence operations via this interface.</para>
    /// </summary>
    public interface IPersistence
    {
        /// <summary>
        /// <see cref="FileObject"/>文件的扩展名。
        /// Extension name of <see cref="FileObject"/>'s file.
        /// </summary>
        string Extension { get; }

        /// <summary>
        /// 将文件对象序列化为文件。
        /// <para>Serialize the specified <paramref name="item"/> into <paramref name="fullname"/>.</para>
        /// </summary>
        /// <param name="item">要进行序列化的文件对象。<para>file object to be serialized.</para></param>
        /// <param name="fullname">要保存到的文件的绝对路径。<para>file's fullname.</para></param>
        /// <returns></returns>
        void Serialize([Required] FileObject item, [Required] string fullname);

        /// <summary>
        /// 将文件反序列化成文件对象。
        /// <para>Deserialize the specified file to an instance of <paramref name="TFileObject"/>.</para>
        /// </summary>
        /// <typeparam name="TFileObject"></typeparam>
        /// <param name="serializedFileObject"></param>
        /// <returns></returns>
        TFileObject Deserialize<TFileObject>([Required] string fullname) where TFileObject : FileObject;
    }

使用接口ISerializable，让每个FileObject都自行处理自己的字段、属性的序列化和反序列化动作（保存、忽略等）。

    /// <summary>
    /// 可在文件数据库中使用CRUD操作的所有类型的基类。类似于关系数据库中的Table。
    /// Base class for all classed that can use CRUD in SharpFileDB. It's similar to the concept 'table' in relational database.
    /// </summary>
    [Serializable]
    public abstract class FileObject : ISerializable
    {
        /// <summary>
        /// 用以区分每个Table的每条记录。
        /// This Id is used for diffrentiate instances of 'table's.
        /// </summary>
        public Guid Id { get; internal set; }

        /// <summary>
        /// 创建一个文件对象，在用<code>FileDBContext.Create();</code>将此对象保存到数据库之前，此对象的Id为<code>Guid.Empty</code>。
        /// <para>Create a <see cref="FileObject"/> whose Id is <code>Guid.Empty</code> until it's saved to database by <code>FileDBContext.Create();</code>.</para>
        /// </summary>
        public FileObject()
        {
        }

        /// <summary>
        /// 生成文件名，此文件将用于存储此<see cref="FileObject"/>的内容。
        /// Generate file name that will contain this instance's data of <see cref="FileObject"/>.
        /// </summary>
        /// <param name="extension">文件扩展名。<para>File's extension name.</para></param>
        /// <returns></returns>
        internal string GenerateFileName([Required] string extension)
        {
            string id = this.Id.ToString();

            string name = string.Format(CultureInfo.InvariantCulture, "{0}.{1}", id, extension);

            return name;
        }

        public override string ToString()
        {
            return string.Format("Id: {0}", this.Id);
        }

        const string strGuid = "Guid";

        #region ISerializable 成员

        /// <summary>
        /// This method will be invoked automatically when IFormatter.Serialize() is called.
        /// <para>You must use <code>base(info, context);</code> in the derived class to feed <see cref="FileObject"/>'s fields and properties.</para>
        /// <para>当使用IFormatter.Serialize()时会自动调用此方法。</para>
        /// <para>继承此类型时，必须在子类型中用<code>base(info, context);</code>来填充<see cref="FileObject"/>自身的数据。</para>
        /// </summary>
        /// <param name="info"></param>
        /// <param name="context"></param>
        public virtual void GetObjectData([Required] SerializationInfo info, StreamingContext context)
        {
            info.AddValue(strGuid, this.Id.ToString());
        }

        #endregion

        /// <summary>
        /// This method will be invoked automatically when IFormatter.Serialize() is called.
        /// <para>You must use <code>: base(info, context)</code> in the derived class to feed <see cref="FileObject"/>'s fields and properties.</para>
        /// <para>当使用IFormatter.Serialize()时会自动调用此方法。</para>
        /// <para>继承此类型时，必须在子类型中用<code>: base(info, context)</code>来填充<see cref="FileObject"/>自身的数据。</para>
        /// </summary>
        /// <param name="info"></param>
        /// <param name="context"></param>
        protected FileObject([Required] SerializationInfo info, StreamingContext context)
        {
            string str = (string)info.GetValue(strGuid, typeof(string));
            this.Id = Guid.Parse(str);
        }
    }

另外，FileObject在使用new FileObject();创建时不为其指定Guid，而在FileDBContext.Create(FileObject)时才进行指定。这样，在反序列化时就不必浪费时间去白白指定一个即将被替换的Guid了。这也更合乎情理：只有那些已经存储到数据库或立刻就要存储到数据库的FileObject才有必要拥有一个Guid。

用一个DefaultPersistence类型代替了BinaryPersistence和XmlPersistence。由于SoapFormatter和BinaryFormatter是近亲，而XmlSerializer跟他们是远亲；同时SoapFormatter和BinaryFormatter分别实现了文本文件序列化和二进制序列化，XmlSerializer就更不用出场了。因此现在不再使用XmlSerializer。

    /// <summary>
    /// 用<see cref="IFormatter"/>实现<see cref="IPersistence"/>。
    /// <para>Implement <see cref="IPersistence"/> using <see cref="IFormatter"/>.</para>
    /// </summary>
    public class DefaultPersistence : IPersistence
    {
        private System.Runtime.Serialization.IFormatter formatter;

        public DefaultPersistence(PersistenceFormat format = PersistenceFormat.Soap)
        {
            switch (format)
            {
                case PersistenceFormat.Soap:
                    this.formatter = new System.Runtime.Serialization.Formatters.Soap.SoapFormatter();
                    this.Extension = "soap";
                    break;
                case PersistenceFormat.Binary:
                    this.formatter = new System.Runtime.Serialization.Formatters.Binary.BinaryFormatter();
                    this.Extension = "bin";
                    break;
                default:
                    throw new NotImplementedException();
            }
        }

        public enum PersistenceFormat
        {
            Soap,
            Binary,
        }

        #region IPersistence 成员

        private string extension;
        public string Extension
        {
            get { return this.extension; }
            private set { this.extension = value; }
        }

        public void Serialize(FileObject item, string fullname)
        {
            if (item == null)
            {
                throw new ArgumentNullException("item");
            }

            if (string.IsNullOrEmpty(fullname))
            {
                throw new ArgumentNullException("fullname");
            }

            using (FileStream s = new FileStream(fullname, FileMode.Create, FileAccess.Write))
            {
                formatter.Serialize(s, item);
            }
        }

        public TFileObject Deserialize<TFileObject>(string fullname) where TFileObject : FileObject
        {
            if(string.IsNullOrEmpty(fullname))
            {
                throw new ArgumentNullException("fullname");
            }

            TFileObject fileObject = null;

            using (FileStream s = new FileStream(fullname, FileMode.Open, FileAccess.Read))
            {
                object obj = formatter.Deserialize(s);
                fileObject = obj as TFileObject;
            }

            return fileObject;
        }

        #endregion

    }

2015-06-23

把FileObject重命名为Document。追随LiteDB的命名。 

新增Demo项目MyNote，演示如何使用SharpFileDB。

 2015-06-24

经不完全测试，当写入同一文件夹内的文件数目超过百万时，下述序列化方式所需时间加倍。

                    using (FileStream s = new FileStream(fullname, FileMode.Create, FileAccess.Write))
                    {
                        formatter.Serialize(s, string.Empty);
                    }

继续测试中。

2015-06-25

根据上述试验和对事务、索引等的综合考虑，决定不再采用“一个数据库记录(Document)放到一个单独的文件里”这种方案。因此到目前为止的SharpFileDB作为初次尝试的版本，不再更新，今后将重新设计一套单文件数据库。

我把这个版本的项目源码放到这里。它超级简单，只有3个类，你不需懂SQL，只要会用C#就能使用。还附有一个Demo：便条(MyNote)，你可以参考。

如果你的应用程序所需保存的数据库记录在几万条的规模，用这个是没问题的。

点此下载源码SharpFileDB.Version0.1.MultiFiles

Document这个类代表一条数据库记录。

    [Serializable]
    public abstract class Document : ISerializable
    {
        public Guid Id { get; internal set; }

        public Document()
        {
        }

        internal string GenerateFileName(string extension)
        {
            string id = this.Id.ToString();

            string name = string.Format(CultureInfo.InvariantCulture, "{0}.{1}", id, extension);

            return name;
        }

        public override string ToString()
        {
            return string.Format("Id: {0}", this.Id);
        }

        /// <summary>
        /// 使用的字符越少，序列化时占用的字节就越少。一个字符都不用最好。
        /// <para>Using less chars means less bytes after serialization. And "" is allowed.</para>
        /// </summary>
        const string strGuid = "";

        #region ISerializable 成员

        public virtual void GetObjectData(SerializationInfo info, StreamingContext context)
        {
            string id = this.Id.ToString();
            info.AddValue(strGuid, id);
        }

        #endregion

        protected Document(SerializationInfo info, StreamingContext context)
        {
            string str = info.GetString(strGuid);
            this.Id = Guid.Parse(str);
        }
    }

这个类就是被设计了用做基类供使用者继承的；另外也需要对其进行序列化，所以我希望 const string strGuid = "";  有两个特点：

1最短（减少序列化后的字节数）很明显，单个字符最短了。一个字符都不用那是不行的。

2最不易被别人重复使用（比如我要是用 const string strGuid = "a"; 什么的，别人在子类型中也出现的概率就比"~"大）

经测试发现，BinaryFormatter可以接受 const string strGuid = ""; 所以改用这个设定。

2015-07-06

根据现有代码和从LiteDB得到的启发，决定重新设计编写一个单文件数据库。目前的代码全部作废，不过保留起来备用，因为其中一些最基础的功能还是会用到的。

待完成的工作

必须支持事务ACID。

必须使用索引。参考LiteDB的skip list方式。

必须分页，每页4096bytes。这是读写磁盘文件的最小单位。充分利用之，可以提升I/O效率。（https://github.com/mbdavid/LiteDB/wiki/How-LiteDB-Works）

PS：我国大多数县的人口为几万到几十万。目前，县里各种政府部门急需实现信息化网络化办公办事，但他们一般用不起那种月薪上万的开发者和高端软件公司。我注意到，一个县级政府部门日常应对的人群数量就是万人左右，甚至常常是千人左右。所以他们不需要太高端复杂的系统设计，用支持万人级别的数据库就可以了。另一方面，初级开发者也不能充分利用那些看似高端复杂的数据库的优势。做个小型系统而已，还是简单一点好。

所以我就想做这样一个小型文件数据库，我相信这会帮助很多人。能以己所学惠及大众，才是我们的价值所在。